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HANDY REFERENCE CARO 

valFORTH ' 

SOFTWARE SYSTEM 

EDITOR 1.1 COMMAND SUMMARY 


Below Is a quick reference list of *11 the contends which the video editor 
recognizes. 


Entering the Edit Mode (executed outside of the edit mode) 


V ( scr* — ) 

l ! — ) 

WHERE ( — l 

LOCATE cccc ( — } 

LOCATOR ( OH/OFF — ) 

*8UFS ( Flints — ) 


* Enter the edit node end view the specified screen. 

* Re-view the current screen. 

* Enter the edit node *nd position the cursor over 
the word that caused « compilation error. 

Enter the edit node and position the cursor over 
the word "cccc" where It Is defined. 

When Oh, allows all words compiled until the next 
OFF to be locatable using the LOCATE command above. 
Sets the length tin lines) of the storage buffer. 
The default Is five. 


Cursor Movement (issued within the edit mode) 


Ctrl t 

Ctrl 4r 

Ctrl *- 

Ctrl 
RETURN 
TAB 


a Hove cursor up one line, wrapping to the bottom line 
If moved off the top. 

• Move cursor down one line, wrapping to the tap line 
If moved off the bottom. 

• Hove cursor left one character, wrapping to the 
right edge if moved off the left. 

• Hove cursor right one character, wrapping to the 
left edge if moved off the right. 

Position the cursor at the beginning of the next 
line. 

Advance to next tabular colixma. 


Editing Commands (Issued within the edit mode) 


Ctrl IMS 

Ctrl DEL 

shift IMS 

shift DEL 

Ctrl I 

BACKS 

Ctrl H 


Insert one blank at cursor location, losing the 
last character on the line. 

Delete character under cursor, closing the line. 

• Insert blank line above current line, losing the 
last line on the screen. 

• Delete current cursor line, closing the screen. 
Toggle insert-mode/replace-mode. 

(see full description of ctrl-I). 

• Delete last character typed, if on the same line 
as the cursor. 

Erase to end of line (Hack). 


Buffer Management (issued within the edit mode) 


Ctrl T 

Ctrl F 

Ctrl K 

Ctrl U 

Ctrl R 

Ctrl • 

Ctrl C 


Delete current cursor line sending 
It to the edit buffer for later use. 

Take the current buffer line and Insert It 
above the current cursor line. 

Copy current cursor line sending It to the 
edit buffer for later use. 

Take the current* buffer line and copy It 
to the current cursor line. 

Roll the buffer making the topmost buffer 
line current. 

Roll the buffer backwards making the fourth 
buffer line on the screen current. 

Clear the current* buffer line and performs 
a ctrl-B. 


•Note: The current buffer line Is bottommost on the video dlspley. 


Changing Screana (Issued within the edit mode) 


Ctrl P 

Ctrl M 

Ctrl S 

Ctrl Q 


Display the previous screen saving all 
changes made to the current screen. 

Display the next screen saving all changes 
made to the current screen. 

* Save the changes made to the current screen 
and end the edit session. 

• Quit the edit session forgetting all changes 
made to the current screen. 


Spacial Kaya (Issued within the edit mode) 


ESC 


Ctrl 

C 

Ctrl 


- J 
0 


* Oo not Interpret the next key typed as any 
of the coamiands above. Send it directly to 
the screen instead. 

Put the arrow ("next screen") In the 

lower-right-hand corner of the screen unless 
it is already there. In whicn case remove It. 

Split the current line into two lines at the point 
where the cursor is. 

Corrects any major editing blunders. 


Screen Management (executed outside of o* edit me) 


flush 

t -) 


a 

EHPTY- 

< -1 


a 

BUFFERS 




COPY 

( fro. 

to - ) 

a 

CLEAR 

( Serf 

- ) 

a 

CLEARS 

( scr# 

♦screens — ) 


SHOVE 

( fro* 

to Iscreens — 

) 


-*■?.- 




Save any updated FORTH screens to disk. 

Forget any changes made to any screens not yet 
FLUSHed to disk. 

Copies screen #from to screen #to. 

Blank fills specified screen. 

Blank fills the specified number of screens start¬ 
ing with screen scr#. 

Duplicate the specified number of screens Starting 
with screen number "from". 


* EDITOR 1.0 COMMAND 
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HANDY REFERENCE CARD 

va!FORTH.1.1 

T.y. 


Suck Inputs and outputs are Shown; top of suck on right. 
This card follows usage of the Forth Inurest Group 
(S.F. Bay Area); usage aligned with the Forth 78 
International SUndard. 

For more info: Forth Interest Group 

P.0. Box 1105 
San Carlos. CA **070. 


Operand Key: n.nl. 

.. 16-bit signed numbers 

d.dl. 

.. 32-bit signed numbers 

u 

16-bit unsigned number 

addr 

address 

b 

8-bit byte 

c 

7-bit ascii ciwnctw »ala» 

f 

boolean flag 

fp 

floating point matter 

S 

string 


Stack Manipulation 

DUP ( n — n n ) 

DROP ( n — ) 

SWAP ( nl n2 — «i2 nl ) 

OVER i nl n2 ~ nl n2 nl ) 

ROT ( nl n2 n3 — n2 n3 nl ) 

<R0T ( nl n2 n3 — n3 nl n2 ) 

-DUP ( n ~ n ? ) 

>A ( n — ) 

R> ( — n ) 

R ( ~ n ) 


Number Bases 

W DECIMAL ( - ) 

HEX ( - ) 

BASE ( — addr ) 


Duplicate top of suck. 

Throw away top of stack. 

Reverse top two suck Items. 

Make copy of second 1 tea on top. 

Route third itea to top. 

RotaU top itea to third. 

Duplicate only If non-zero. 

Move top itea to "return suck* for teaporary 
storage (use caution). 

Retrieve itea from return sUck. 

Copy top of return stack onto stack. 


Set deciaal case. 

Set hexadeclaal base. 

Systea variable containing nuaber base. 


Arithmetic end Logical 

♦ 

( nl n2 — sum ) 

D* 

( dl d2 — sum ) 

_ 

( nl n2 — diff ) 

• 

( nl n2 — prod ) 

/ 

( nl n2 — quot ) 

MOO 

( nl n2 — rem ) 

/MOD 

( nl n2 — rem quot ) 

VMOO 

( nl n2 n3 — rem quot) 

V 

( nl n2 n3 — quot ) 

MAX 

( nl n2 — max ) 

MIN 

( nl n2 — min ) 

ABS 

( n — absolute ) 

DABS 

( d — absolute } 

MINUS 

( n - -n ) 

OMINUS 

( d - -d ) 

AND 

( nl n2 — and ) 

OR 

( nl n2 — or ) 

X0R 

( nl n2 — xor ) 

NOT 

( n - f ) 


Add. 

Add double-precision matters. 

Subtract (nl-n2). 

Multiply. 

Divide (nl/n2). 

Modulo (i.e. reaainder froa division). 

Divide, giving reaainder and quotient. 
Multiply, then divide (nl*n2/n3), with double- 
precision InteraadlaU. 

Like VMOO, but give quotient only. 

Maxiaua. 

Mlnlaua. 

Absolute value. 

AbsoluU value of double-precision natter . 
Change sign. 

Change sign of double-precision nuaber. 

Logical AMO (bitwise). 

Logical OR (bitwise). 

Logical exclusive 0* (bitwise). 

True if top nuaber zero (i.e. r everses 
truth value). 


Comparison 


< 

( nl n2 - f ) 

True If nl less than n2. 

> 

( nl n2 - f ) 

True if nl greater than n2. 

<■ 

( nl n2 - f ) 

True if nl less than or equal to n2. 

>* 

( nl n2 - f ) 

True If nl greater than or equal to n2. 


( nl n2 - f ) 

True if top two nutters are equal. 

o 

( nl n2 - f ) 

True if nl does not equal n2. 

Ck 

( n - f ) 

True if top number negative. 

o> 

( n - f ) 

True if top nuaber positive. 

0- 

( n - f ) 

True If top nutter zero (I.e. reverses 

0# 

( n - f ) 

truth value. 

True If n does not equal zero. 

Memory 



t 

( addr — n ) 

Replace word address by contents. 

• 

( n addr — ) 

Store second word at address om top. 

CP 

( addr — b ) 

Fetch one byte only. 

Cl 

( b addr — ) 

Store one byte only. 

? 

( addr — ) 

Print contents of address. 

c? 

( addr — ) 

Print byte at address. 

U? 

( aodr — ) 

Print unsigned contents of address. 

♦ ! 

( n addr — ) 

Add second nutter on stack to contents of address 
on top. 

CMOVE 

( from to u — ) 

Move u bytes in memory from head to head. 

<CM0VE 

( from to u — ) 

Move u bytes in memory from tail to tall. 

FILL 

( addr u b — ) 

Fill u bytes in memory with b, beginning at 
address. 

ERASE 

( addr u — ) 

Fill u bytes In memory with zeroes, beginning at 
address. 

BLANKS 

( addr u — ) 

Fill u bytes In mamory with blanks, beginning at 


addmi. 


Control Structures 

00. ..LOOT da: ( «M»1 Itirt — ) 
I ( — Index 

I # ( — Index 

J ( - index 

LEAVE ( - ) 

7EXIT ( - ) 

00... HOOP do: ( end*l SUrt — \ 
♦loop: ( a — ) 

00... /LOOP do: ( end+1 SUrt — ) 
/loop: { u — ) 

IF...(true) if: ( f - ) 

...EN0IF 
IF...(true) 

...aSE If: (f - ) 

...(false) 

...ENDIF 

BEGIN... until: ( f - ) 

UNTIL 

BEGIN... while: (f - ) 

WHILE 

...REPEAT 


Set up loop, given index range. 

Place current index value on stack. 

Used to retrieve index after a >R. 

Place index of outer D0-L00P on stack. 

Terminate loop at next LOOP, HOOP, or /LOOP. 
LEAVE If 7TERMINAL is true (I.e. pressed). 

Like DO...LOOP, but adds stack value (instead of 
always *1') to index. 

Like DO... HOOP, but adds unsigned value to 
Index. 

If top of stack true (non-zero), execute. (Note: 
Forth 78 uses IF...THEM.) 

Sane, but If false, execute ELSE clause. (Note: 
Forth 78 uses IF...ELSE...THEN.) 

Loop back to BEGIN until true at UNTIL. (Note: 
Forth 78 uses BEGIN...ENO.) 

Loop while true at WHILE-.REPEAT loops uncondition¬ 
ally to BEGIN. (Note: Forth 78 uses BEGIN...IF 
...AGAIN.) 


Terminal Input - Outpu 

. 

<»- i 

.R 

< ■ rttidridtk — 

D- 

( <i -- ) 

D.R 

( d f1,l*ridtb — 

CR 


SPACE 

( - 1 

SPACES 

( » - ) 

. * 

( “ ) 

DUMP 

( »ddr a — ) 

TYPE 

( addr a -- ) 

COUNT 

( addr - addr-1 a 

7TERMINAL 

( - M 

KEY 

( - c ) 

EMIT 

( c - ) 

EXPECT 

( addr a - ) 

MONO 

t « — 1 

Cl.S 


Input - 

Output Forma tin 

NUfBER 

( addr - d ) 

<1 


1 

I d _ d ) 

#S 

( d - 0 0 ) 

SIGN 

( » d - d ) 

#> 

( d - addr a ) 

HOLD 

( c - ) 

Disk Handing 

LIST 

( screen — ) 

LOAD 

( screen — ) 

BLOCK 

( block — addr ) 

B/BUF 

( - n ) 

BLK 

- addr 1 

SCR 

( - addr ) 

UPDATE 

( - ) 

ausM 

( -- ) 

EMPTY- 

( - ) 

BUFFERS 



Print matter. 

Print matter, right-Justified In field. 

Print double-precision nuaber 

Print double-precision matter, right-justified In 

field. 

Do a carriage return. 

Type one space. 

Type n spaces. 

Print Message (terminated by "). 

Dump u words starting at address. 

Type string of u characters starting at address. 
Change length-byte string to TYPE form. 

True if terminal break request present. 

Read key, put ascii value on stack. 

Type ascii value from stack. 

Read n characters (or until carriage return) from 
Input to address. v 

Read one word from Input stream, using given 
character (usually blank) as delimiter. 

c Scm'lV 


Convert string at address to double-precision nutter. 
Start output string. 

Convert next digit of double-precision nutter and 
add character to output string. 

Convert all significant digits of double-precision 
nutter to output string. 

Insert sign of n Into output string. 

Terminate output string (ready for TYPE). 

Insert ascii character Into output string. 


List a disk screen. 

Load disk screen (compile or execute). 

Read disk block to memory address. 

System constant giving disk block size In bytes. 
System variable containing current block nutter. 
System variable containing current screen number. 
Nark last buffer accessed as updated. 

Write all updated buffers to disk. 

Erase all buffers. 


Defining Words 


: xxx 

VARIABLE xxx 
CONSTANT xxx 
CODE xxx ( 
;COOE ( 


( * — 
xxx: ( 
( n — 
xxx: ( 
- ) 
* 

- ) 


) 

)* 


•dtt ) 

• ) 


<BUILDS... does: ( - addr ) 
D0ES> 

LABEL xxx ( - addr ) 


Begin colon definition of xxx. 

End colon definition. 

Create a variable named xxx with initial value n; 
returns address when executed. 

Create a constant named xxx with value n; returns 
value when executed. 

Begin definition of assembly-language primitive 
operative named xxx. 

Used to create a new defining word, with execution¬ 
time "code routine” for this data type In asseafcly. 
Used to create a new defining word, with execution¬ 
time routine for this data type in higher-level Forth. 
Creates a header xxx which when executed returns its 
PFA. 
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- vaiFORTH 6502 Assembler 


ASSEMBLER 

(— i 

Calls up the assembler vocabulary for subsequent 
assembly language programming. 

CODE xxx 

t — i 

Enters the new word "xxx" Into the dictionary 
as machine language word and calls up the 
assembler vocabulary for subsequent assembly 
language programming. 

C; 

i — i 

Terminates an assaably language definition by 
performing a security check and setting the 
CONTEXT vocabulary to the same as the CURRENT 
vocabulary. 

END-CODE 

(—) 

A coemonly used synonym for the word C; above. 
The word C; Is recommended over END-CODE. 

SUBROUTINE 

IXX (-) 

Enters the new word "xxx" Into the dictionary 
as machine language subroutine and calls up 
the assembler vocabulary for subsequent assmbly 
language programing. 

;C0DE 

Control 

() 

Structures 

When the assembler is loaded, puts the system 
into the assembler vocabulary for subsequent 
assembly language programming. See mein 
glossary for further explanation. 


IF, (flag — addr 2 ) Begins a Machine language control structure 

based on the 6502 status flag on top of the 
stack. Leaves an address and a security check 
value for the ELSE, or ENOIF. clauses below, 
-flag" can be EQ , HE . CC , CS , VC , VS , 

HI , or PL . Coanand forms: 

...flag..!F,..1f-true..ENDIF,...a11.., 
...flag..IF,..1f-true.. 

ELSE,..if-false..EIttIF,..*11... 

ELSE, ( addr 2 — addr 3 ) Used In an IF, clause to allow for execution 

of code only If IF, clause Is false. If the IF, 
clause Is true, this code Is bypassed. 

ENOIF, ( addr 2/3 — ) Used to terminate an IF, control structure 

clause. Additionally, ENOIF, resolves all 
forward references. See IF, above for amend 
fom. 


Begins machine language control structures of 
the following forms: 

...BEGIN,...AGAIN,... 

...BEGIN,...flag..UNTIL,... 

.. .BEGIN.... Hag. .MHILE,. .whl le-true. .NEPEAT,... 
*diere "nag" is one of the 6502 statuses: EQ , 
NE , CC , CS , VC , VS , HI . and PL . 

Used to terminate a post-testing BEGIN, clause 
thus allowing for conditional looping of a 
program segnent while "flag" is false. 

WHILE, { addr 1 flag — addr 4 ) Used to begin a pre-testing BEGIN, clause thus 

allowing for conditional looping of a program 
segment while “Hag" is true. 

REPEAT, ( addr 4 — ) Used to terminate a pre-testing BE6IN,. .WHILE, 

clause. Additionally, REPEAT, resolves all 
forward addresses of the current WHILE, clause. 

AGAIN, { addr 1 — ) Used to terminate an unconditional BEGIN, 

clause. Execution cannot exit this loop unless 
a JHP, Instruction is used. 

Parameter Passing (These routines must be junped to.) 


BEGIN, ( — addr l ) 


TIL, ( addr 1 flag — ) 


NEXT 

( — addr ) 

PUSH 

( — (Mr ) 

PUSHOA 

( — addr ) 

PUT 

( — addr ) 

PUTOA 

( — addr ) 

BINARY 

( — addr ) 

POP and 
POPTWO 

( — addr ) 

SETUP 

( — addr ) 

R 

( — addr ) 

Opcodes 

( various — 


Aliases 



NXT. • NEXT JHP. 

PSH, • PUSH JHP, 

PUT, • PUT JHP, 

PSHA, - PUSHOA JHP, 
PUTA, ■ PUTOA JHP, 
POP, ■ POP JHP, 


Transfers control to the next FORTH word to bo 
executed. The parameter stack Is left unchanged. 
Pushes a 16 bit value to the parameter suck 
whose low byte Is found on the 6502 return 
stack and whose high byte is found In the 
accumulator. 

Pushes a 16 bit value to the paramter suck 
whose low byte Is found in the accumulator and 
whose high byte Is zero. 

Replaces the value currently on top of the 
parameter sUck with the 16 bit value whose 
low byte is found on the 6502 stack and whose 
high byte is In the accmulator. 

Replaces the value currently on top of the 
parameter sUck with the 16 bit value whose 
low byte is in the acciaulator and whose high 
byte is set to zero. 

Drops the top value of the parameter stack 
and then performs a PUT operation described 
above. 

POP drops one value from the paramour stack. 
POPTWO drops two values from the parameUr 
suck. 

Hoves one to four values to the N scratch arms 
In the zero page and drops all values moved 
from the parameUr suck. 

Points to a nine-byte scratch area In the zero 
page beginning at N-l and going to N+7. 


ADC. 

A NO, 

ASl, 

BIT. 

BRK, 

CLC. 

ao. 

ai. 

av. 

CMP, 

CPX, 

CPY, 

DEC. 

DEX. 

0EY, 

EOR, 

INC. 

INX, 

INT, 

JSR, 

JHP. 

LOA, 

LDX, 

LDY, 

LSR, 

NOP, 

ORA. 

pm. 

PHP, 

PLA, 

PIP. 

NX, 

ROR. 

RTI. 

RTS, 

SBC, 

SEC. 

SED. 

SEI. 

STA, 

STX. 

TAX, 

TAY, 

TSX, 

TXA, 

TXS, 

TYA, 



POP2. 


POPTWO JHP 

XL. 


XSAVE LDX, 

XS, 


XSAVE STX, 

THEN, 


ENOIF. 

END. 


UNTIL, 
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Graphics and Color 

SETCOLOR 

( nl n2 n3 — ) 

SE. 

( nl n2 n3 -- ) 

GR. 

( « - ) 

POS. 

( i y - ) 

POSIT 

< * y -- ) 

PLOT 

< * y — ) 

DRAWTO 

( « y - ) 

OR. 

( « y - ) 

FIL 

( b ~ ) 

G" 

( -- ) 

GTYPE 

( rtdr count — ) 

LOC. 

< x y ~ b ) 

<G") 

< - 1 

POSR 

( - « y ) 

CPUT 

( b - ) 

CGET 

( - b ) 

>SCD 

( cl - c2 ) 

SCD> 

( cl - C2 ) 

>BSCD 

( iddrl ,ddr2 count 

BSCQ> 

( iddrl ,ddr2 count 

COLOR 

( b - ) 

CLR8YT 

( — addr ) 


GREY - 0 PINK 

GOLO - 1 LVNOR 

ORNC — 2 BtPRPL - 

ROORNG - 3 PRPLH - 

SOUND ( chan freq dlst vol 


SO. ( chan freq dlst vol 

FILTER! { n — } 

AUDCTL { - addr ) 

XSND ( n — ) 

XSMD4 { — ) 


Color register nl (0...3 and 4 for background) 

Is set to hue n2 (0 to 15) and 1 uninance n3 
(0-14, even)** 

Alias for SETCOLOR. 

Identical to GR. in BASIC. Adding 16 will 
suppress split display. Adding 32 will suppress 
display oreclear. In addition, this GR. will 
not disturb player/misslles. 

Sane as BASIC POSITION or POS. Positions the 
invisible cursor If in a split display node, 
and the text cursor If in 0 GR. . 

Positions and updates the cursor, slaHler to 
PLOT, but without changing display data. 

Sane as BASIC PLOT. PlOTs point of color In 
register specified by last COLOR connand, at 
point x y. 

Sane as BASIC DRAtfTO. Draws line fron last 
PLOT’ted, DRANTO’ed or POSIT’ed point to x y, 
using color in register specified by last COLOR 
coaannd. 

Alias for DRAWTO. 

Fills area between last PLOT’ted, DRAWTO'ed or 
POSIT’ed point to last position set by POS.. 
using the color in register b. 

Used in the form G" ccccc". Sends text cccc to. 
text area in non-0 Graphics node, starting at 
current cursor position. In color of register 
specified by last COLOR connand prior to cccc 
being output. 

Starting at addr, output count characters to 
text area in non-0 Graphics node, starting at 
current cursor position, in color of register 
specified by last COLOR connand. 

Positions the cursor at x y and fetches the 
data fron display at that position. Like 
BASIC LOCATE and LOC. . 

Run-tine code conpiled in by 6*. 

Leaves the x and y coordinates of the cursor 
on the stack. 

Outputs the data b to the current cursor 
position. 

Fetches the data b fron the current cursor 
position. 

Converts cl fron ATASCII to its display screen 
code. c2. Exanple: ASCII A >SC0 88 $ Cl 
will put an "A" into the upper left comer of 
the display. 

Converts cl fron display screen code to ATASCII 
c2. See >SC0. 

) Moves count bytes fron addrl to addr2, 
translating fron ATASCII to display screen 
code on the way. 

) Moves count bytes fron addrl to addr2, 
translating fron display screen code to 
ATASCII on the way. 

Saves the value b In the variable CLR8YT. 
Variable that holds data fron last COLOR 


4 BLUE - 8 

GREEN 

- 12 

5 LTBLUE — 9 

VLWGRN 

- 13 

6 TURQ - 10 

ORNGRN 

— 14 

7 GJWL - 11 

LTORNG 

- 15 

(CONSTANTS) 




} Sets up the sound channel ‘chan* as Indicated. 
Channel: 0-3 

Frequence: 0-255, 0 Is highest pitch. 

Distortion: 0-14, evens only. 

Volune: 0-15. 

Suggested mn e monic: CatFIsh Don't Vote 
) Alias of SOUND. 

Stores n In the audio control register and Into 
the valFORTH shadow register. AUDCTL. Use 
AUDCTL when doing bit nanipulation, then do 
FILTER!. 

A variable containing the last value sent to the 
audio control register by FILTER!. 

Silences channel n. 

Silences all channels. 


Text Output and Disk Preparation 


S: 

( flpg - ) 

If flag is true, enables handler that sends 
text to text screen. If false, disables the 
handler. (See PFLA6 In eein glossary.) 

P: 

< flip ~ > 

If flag is true, enables handler that sends 
text to printer. If false, disables the 
handler. (See PFIA6 in aain glossary) 

BEEP 

(-- > 

Makes a raucous noise from the keyboard. 

ASCII 

( e. -- n {executing) ) 

( c. — (caviling) ) 

Converts next character In input stream to 
ATASCII code. If executing, leaves on stack. 

If compiling, compiles as literal. 

EJECT 

( - ) 

Causes a form feed on smart printers if the 
printer handler has been enabled by ON P:. 

May need adjustment for d mb or nonstandard 
printers. 

LISTS 

f start count — ) 

From start, lists count screens. May be aborted 
by CONSOLE button at the end of a screen. 

PI 1ST 

( scr - ) 

Lists screen scr to the printer, then restores 
former printer handler status. 

PIISTS 

( start cat — ) 

From start, lists ent screens to printer three 
to a page, then restores former printer handler 
status. May be aborted by CONSOLE button at 
the end of a screen. 

FORMAT 

( -- ) 

With prompts, will format a dish In drive of 
your choice. 


Debugging Utilities 


DECO* 

XJU 

COUP* 

( ubdr x — ) 

POUMP 

( wttr , - ) 

(FREE) 

t ~ • ) 

FREE 

( - ) 

It 

( » - ) 

STACK 

i "H -- ) 

.S 

( ... - ... ) 

u.s 

( ... - ... ) 

B? 

( - ) 

CFALIT 

ox ( — cfa («i*cut1ng)) 
XXX ( — (caviling)) 

Floating Point 

FCONSTANT 

xax ( fg — ) 

*** ( - fp ) 

fvarimle 

xrn (fp — ) 
xxx: ( tddr — ) 

FOUR 

( fpl - fp! fpl ) 

FOROP 

( fp — ) 

FOVER 

( fp2 fpl - fp2 fpl fp2 

FLOATING 

xxx ( — fp ) 

FP 

xxx ( - fp ) 

Ft 

( Mr — fp ) 

F! 

( fp ‘Mr — ) 

F. 

( fp - ) 

F? 

( xdrir — ) 

F+ 

( fp2 fpl - fp3 ) 

F- 

( fp2 fpl - fp3 ) 

F* 

( fp2 fpl - fp3 ) 

F/ 

( fp2 fpl - fpl ) 

FLOAT 

( » — fp ) 

FIX 

( fp (non-i*g. IttI 
tbPn 32767.5) - ■ ) 

LOG 

( fpl - fp2 ) 

LOG 18 

( fpl - fp2 ) 

EXP 

( fpl - fp2 ) 

EXP 10 

( fpl - fpl ) 

FO- 

t fp - fl»g ) 

P- 

( fpl fpl - flpg ) 

F> 

( fp2 fpl - flpg ) 

F< 

( fpi fpl ~ flag ) 

FLITERAL 

( fp - ) 

Operating System 

OPEN 

( Pddr nO xl nl — «3 ) 

CLOSE 

( n - ) 

PUT 

t bl n - K ) 

GET 

(■-UK) 

GETREC 

( Ppdr nl n2 — n3 ) 

PUTREC 

( p*Pr nl n2 - n3 ) 

STATUS 

( « — b ) 

OCVSTAT 

i n - bl b2 b3 ) 

SPECIAL 

( kl U U M H bi 

67 M - U ) 

RS232 

( - ) 


Does a decompilation of the word xxx If It can 
be found In the active vocabularies. 

A character diaap from addr for at least n 
characters. (Hill always do a multiple of 16.) 

A numerical dump in the current base for at 
least n characters. (Will always do a Multiple 
of 8.) 

Leaves number of bytes between bottom of display 
list and PAD. 

Ooes (FREE) and then prints the stack and 
"bytes". 

Prints n In HEX, leaves BASE unchanged. 

If flag is true, turns on visible stack. 

If flag is false, turns off visible stack. 

Does a signed, nondestructive stack printout, 

TOS at right. Also sets visible stack to do 
signed printout. 

Does unsigned, nondestructive stack printout, 

TOS at right. Also sets visible stack to do 
unsigned printout. 

Prints the current base, in decimal. Leaves 
BASE undisturbed. 

Gets the cfa (code field address) of xxx. If 
executing, leaves it on the stack; if compiling, 
compiles it as a literal. 


The character string is assigned the constant 
value fp. When xxx is executed, fp will be 
put on the stack. 

The character string xxx is assigned the 
initial value fp. When xxx Is executed, the 
addr (tm bytes) of the value of xxx will be 
put on the stack. 

Copies the fp nurter at top-of-stack. 

Discards the fp number at top-of-stack.) 

) Copies the fp number at 2nd-on-stack to 
top-of-stack. 

Attempts to convert the following string, xxx, 
to a fp number. 

Alias for FLOATING. 

Fetches the fp number Wtose address Is at 
top-of-stack. 

Stores fp into addr. Remember that the 
operation will take six bytes in memory. 

Type out the fp number at top-of-stack. 

Ignores the current value in BASE and uses 
base 10. # 

Fetches a fp number from addr and types It out. 
Replaces the two top-of-stack fp items, fp2 and 
fpl, with their fp sum. fp3. 

Replaces the two top-of-stack fp items fp2 and 
fpl, with their difference, fp3«fp2-fpl. 

Replaces the two top-of-stack fp items fp2 and 
fpl, with their product, fp3. 

Replaces the two top-of-stack fp items fp2 and 
fpl. with their quotient. fp3«fp2/fpl. 

Replaces mwtoer at top-of-stack with Its fp 
equivalent. 

Replaces fp number at top-of-stack, constrained 
as indicated, with Its integer equivalent. 
Replaces fpl with its base e logarithm, fp2. 

Not defined for fpl negative. 

Replaces fpl with its base 10 decimal logarithm, 
fp2. Not defined for fpl negative. 

Replaces fpi with fp2, which equals a to the 
power fpl. 

Replaces fpl with fp2, which equals 10 to the 
power fpl. 

If fp is equal to floating-point 0. a true 
flag is left. Otherwise, a false flag is left. 
If fp2 is equal to fpl, a true flag is left. 
Otherwise, a false flag is left. 

If fp2 is greater than fpl, a true flag Is 
left. Otherwise, a false flag is left. 

If fp2 is less than fpl, a true flag Is left. 
Otherwise, a false flag is left. 

If compiling, then compile the fp stack value 
as a fp literal. 


This *n>rd opens the device whose name 1$ at 
addr. The device is opened on channel nO with 
AUX1 and AUX2 as nl and n2 respectively. The 
device status byte Is returned as n3. 

Closes channel n. 

Outputs byte bl an channel n, returns status 
byte b2. 

Gets byte bl from channel ft, returns status 
byte b2. 

Inputs record from channel n2 up to length el. 
Returns status byte n3. 

Outputs nl characters starting at addr through 
channel n2. Returns status byte n3. 

Returns status byte b from channel n. 

From channel nl gets device status bytes bl and 
b2, and normal status byte b3. 

Implements the Operating System "Special" 
command. AUX1 through AUX6 art bl through b6 
respectively, command byte is b7, channel number 
Is b8. Returns status byte b9. 

Loads the Atari 850 drivers Into the dictionary 

(approx 1.8K). 
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Csss Structures 


CASE: structure Sa Structure 

Format: Forwt: 


CASE: 

wordnaae 

: wordoaw,- 

— 

wordO 

’T- 


Mordl 

XL 



•1 -» wordO 


wordN ; 

*2 -> wordl 

CASE Structure 


nN > wordN 

Format: 


( NOSa wordnone 


SaEKC 

: wordn—e 


...» 



COMO Structure 

CASE 

aordO 


Forwt: 

wordl 



; wnrdnwe 

wonfN 



( NOOSE aordnone } 

COM) 

CASEMD 


conditlonO « 

... ; 


condition! « 


) 


mordsO 
words1 


» 

» 


condition* « wordsn » 
( NOCOND wordsnone } 

CONOENO 


Miscellaneous UtMties 


XR/W 

LOADS 

THRU 

( #stcs addr blk flag — 

( start count — ) 

) "Extended read-write.“ The saw as R/W except 
that XR/W accepts a sector count for wltlple 
sector reads and writes. Starting at address 
addr and block blk, read (flag true) or write 
(flag false) fsecs sectors froa or to disk. 
Loads count screens starting froa screen f 
start. . 


( start finish — 

Converts tno range makers to a start-court 


start count 

) format. 

SEC 

< n — > 

Provides an n second delay. Uses a tuned 
do-loop. 

MSEC 

< • - ) 

Provides an n Billisecond delay, (approx) 

Uses a tuned do-loop. 

H->L 

( nl — aZ ) 

Moves the high byte of nl to the low byte and 
zero's the high byte, creating n2. Machine 
code. 

t->H 

r 

( Bl -- BZ ) 

{ Bl - Bl(hf) nl(lo) ) 

Moves the low byte of nl to the high byte and 
zero’s the low byte* creating n2. Machine code. 
Split top of stack into two stack Iteas: 

New top of stack is low byte of old top of 
suck. New second on suck Is old top of 
stack with low byte zeroed. 

Creates a nuaber n that has only its bth bit 
set. The bits are nuabered 0-15. 


( t — b ) 

Tit 

n it 


( B b - f ) 

Leaves a true flag if the bth bit of n Is set. 
Otherwise leaves a false flag. 


TBIT 

( Bl b — n2 ) 

Toggles the bth bit of nl, waking n2. 

SB IT 

( nl b - b2 ) 

Sets the bth bit of nl, wking n2. 

RBIT 

( Bl b — bZ ) 

Resets the bth bit of nl, aaking n2. 

STICK 

( n — horz vert ) 

Reads the nth stick (0-3) and resolves the 
setting into horizontal and vertical parts, 
with values froa -1 to ♦!. -1 -l aeans up 
and to the left. 

MDOLE 

( Bl - BZ ) 

Reads the nlth paddle (0-7) and returns Its 
value n2. Machine code. 

16TIME 

( - B ) 

Returns a 16 bit tiwr reading froa the systea 
clock at locations 19 and 20, deciaal. 

6RND 

( - b ) 

Leaves one random byte froa the internal 
hardware. Machine code. 

16RHD 

( “ B ) 

Leaves one randoa word froa the Internal 


( at - aZ J 

hardware. Machine code with 20 cycle extra 
delay for rerandoaization. 

CHOOSE 

Randoaly choose an unsigned nuaber u2 which 

Is less than ul. 


CSHUa 

( addr n — ) 

( addr n — ) 

Randoaly rearrange n bytes In aeaory, start¬ 
ing at address addr. 

shufl 

Randoaly rearrange n words In aaaory, start¬ 
ing at address addr. 

( addr n — ) 

DlK 5 

SUrting at addr, duap at least n bytes (even 
aultiple of 8) as ASCII and hex. Mey be 
exited early by pressing a CONSOLE button. 

( addr count b — ) 

BXOR 

Starting at address addr, for count bytes, 
perform bit-wise exclusive OR with byte b at 




each address. 

BAND 

( addr couBt b — ) 

SUrting at address addr, for count bytes* 
perform bit-wise AND with byte b at each 



address. 

BOR 

STRIS 

( addr caant b - ) 

( a — fl»g ) 

SUrting at address addr, for count bytes, 
perform bit-wise OR with byte b at each address. 
Reads the button of joystick n (0-3). 

CTRIG 

( b — flag j 

(trails tht buttoB of padtflt b (0-7). 

<■ 
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HANDY REFERENCE CARD 

va/FORTH 1J valFORTH^ Memory Map 


Vocabularies 


CONTEXT | 

; — «ddr ) 

Returns address of pointer to context vocabulary 
(searched first). 


CURRENT i 

( — *ddr ) 

Returns address of pointer to current vocabulary 
(where new definitions are put). 


FORTH i 

[ - ) 

Main Forth vocabulary (execution of FORTH sets 

CONTEXT vocabulary). 


EDITOR 1 

[ - ) 

Editor vocabulary; sets CONTEXT. 


ASSEMBLER 

! - ) 

Assembler vocabulary; sets CONTEXT. 


DEFINITIONS i 

( - 1 

Sets CURRENT vocabulary to CONTEXT. 


VOCABULARY i 

( - ) 

Create new vocabulary named xxx. 


VLIST 

1 - ) 

Print names of all words in CONTEXT vocabulary. 

DP 

Miscellaneous and System 



( 

( - ) 

Begin comment, terminated by right paren on same 
line; space after ( . 

LIMIT 

FORGET xxx 1 

( - ) 

Forget all definitions back to and including xxx. 


ABORT 

( - ) 

Error termination of operation. 


' XXX 1 

[ — addr ) 

Find the address of xxx in the dictionary; If used 
in definition, compile address. 

FIRST 

HERE i 

( — addr ) 

Returns address of next unused byte in the 


PAD 

[ — addr ) 

dictionary. 

Returns address of scratch area (usually 128 bytes 

$0700 

IN 

! — addr ) 

beyond HERE). 

System variable containing offset Into Input buffer. 

$0600 



Used, e.g., by WORD. 


SP« i 

1 — addr ) 

Returns address of top stack Item. 

$05FF 

ALLOT 

In-) 

Leave a gap of n bytes in the dictionary. 

, 1 

t n - ) 

Compile a number into the dictionary. 

$057E 


8TANDARD DISPLAY 
MEMORY AREA 



GENERAL BUFFER 

'r 


WORD BUFFER 


DICTIONARY 






DISK BUFFERS 

2112 BYTES DECIMAL 
(RELOCATABLE) 

- 


(TASK) 

KERNEL 



BOOT CODE 



ATARI FLOATING POINT 


PAD 

$0080 BYTES 


USE 

PREV 

0 +ORIGIN 


$0480- 
$01FF- 
RP- 
$ 0100 - 
$00FF- 
S00D4- 


USER AREA 


RETURN STACK __---- 

___TERMINAL BUFFER 


-UP 

-R0 

IN 

-TIB 


ATARI FLOATING POINT 


Z PAGE 


UP N IP W 


SO 

SP 


STACK $OOBC-$OOBO 


•P » * WOOTEN 
m It STACK COMTEK 
Of CPU 
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HANDY REFERENCE CARD 

valFORTH M 

SOFTWARE SYSTEM 

GENERflL UTJUTB 


8tring« 

umvt ( *Mrl *ddr2 « — ) 


ccc* ( — 

( -1 


5C0RSTAKT mu ( $ — 

xxx: l -- « ) 


SVARIABLE 

m ( a — 
mu: ( — 

,1 

S. 

i S- ) 


S! 

( 5 addr - ) 

$♦ 

( tl 12 - 

S3 ) 

tens 

1 1! n - 

$2 ) 

RIGHTS 

( J1 n — 

52 ) 

KIDS 

( $1 o u - 12 

IE* 

ASC 

( 5 — lan ) 

( » - c ) 


SCONPARE 

S- 

s< 

s> 

SAVES 

( $1 52 - 
( 51 52 - 
(SI 52 — 
(SI 52 — 

( 51 - 52 

flag 

flag 

flag 

flag 

) 

IRSTR 

( 51 SZ - 

n ) 

CHRS 

( c - 5 ) 


DSTRS 

( d - 5 I 


STRS 

( n - 5 ) 


STRINGS 

( n 51 -- 

52 ) 

#INS 

( n - 5 ) 


INS 

( ~ 5 ) 


S-TB 

SXCHG 

(51-52 
l $1 - 52 

) 

) 


Array Word Glossary 

ARRAY lux ( n — ) 

xxx:( ■ — xddr ) 


CARRAV xxx ( X — ) 

xxx: ( ■ — ARdr ) 


TARLE 


CTAK.E 


VECTOR 


xxx ( — 
xxx:( ■ — i 


xxx ( — 

xxx:£ v ■ 


xxx (xO . 
xxx:( 


•M count 


CVECTOR xxx (00 ... M count - 
xxx:( ■ — Addr 


MOVE lx < "ubIvwmI* wwory xo*e. It takes 
tne block of awwry n bytes long at aOdrl and 
copies It to oeanry location addr2. MOVE 
correctly uses erttier CMOVE or <OOVE. 

(at coanlle tine) 

(at run tlae) 

If caanltlnSi tbe sequence ccc (OellelteC by 
toe trelllns ") Is ceanlled Into tne Ulctlonery 
as a strtns: 

I len I c I c I c I...t c I 
(at coanlle tlae) 

(at execution tlae) 

Takes the strlns on top of tne stack and 
counties It Into tne dictionary witn tne nane 
xxx. When xxx is later executed, the address 
of the string Is pushed onto the stack. 

Reserves space for a string of length n. 

When xxx Is later executed, the address of the 
string Is pushed onto the stack. 

Takes the string on top of the suck and sands 
it to the current output device. 

Takes the string at second on suck and stores 
it at the address on top of suck. 

Takes 52 and concatenates It utth SI, leaving 
S3 at RAD. 

Returns the leftaost "n* characters of SI as 
S2. 

Returns the rlghtawst *n* characters of SI as 

S2. 

Returns S2 of length u suiting with the nth 
character of SI. 

Returns the length of the specified string. 
Returns the ASCII value of the first character 
of the specified string. 

Coapares SI with SZ and returns a sUtus flag. 
Coapares two strings on top of the tuck. 
Coapares two strings on top of the suck. 
Cowares two strings on top of the suck. 

As post string operations leave resulunt 
strings at RAD. the word SAVES is used tt 
tenporarlly aove strings to RAD»512. 

Searches Si for first occurrence of $2. 

Returns the character position in SI If a 
natch is found; otherwise, zero is returned. 
Takes the character *c" and pokes It into a 
string of length one and stores It at RAD. 

Takes the double nianber d and converts it to 
its ASCII representation as S at RAD. 

Takes the single length nuatier n and converts 
it to its ASCII representation as S at RAD. 
Creates S2 as n copies of the first character 
of SI. 

*IRS has three sfallar but different functions. 
If n is positive, it accepts a string of n or 
fewer characurs froa the urainal. If n is 
rero, it accepts up to 2S5 characters froa the 
Urainal. If n is negative, tt returns only 
after accepting -n characurs froa the Urainal. 
The resulunt string is stored at RAD. 

Accepts a string of up to 25S characurs froa 
the Urainal. 

Reaoves trailing blanks froa Si leaving new S2. 
Exchanges the contents of SI with S2. 


(coapiliog) 

(executing) 

When coapiling, creates an array naaed xxx 
with n 16-bit elnaents nunbered 0 thru n-1. 

Initial values are undefined. When executing, 
Ukes an argunent. a, off the suck and lnaus 
the address of elaaent a of the array. 

(coapiling) 

(executing) 

When coapiling, creates a c-array naaed xxx 
with n S-bit elnaents nuabered 0 thru n-1. 

Initial values are undefined. When executing, 
Ukes an argunent, a, off the suck and leaves 
the address of eleaent a of the c-array. 
(coapiling) 

(executing) 

When coapiling, creates a Uble naaed xxx but 
does not allot space. Elnaents are cow lied in 
directly with , (cones). When executing, Ukes 
one argument, a off the SUck and, assuming 
16-bit elnaents, leaves the address of eleaent 
a of the Uble. 

(coapiling) 

(executing) 

When cowiling, creates a c-uble naaed xxx 
but does not allot space. Elements are cowiled 
in directly with C, (c-eowa). When executing, 
Ukes one argument, a off the suck and, asswing 
S-blt elements, leaves the address of etaaant a 
of the c-uble. 

1 (cowlling) 

) (executing) 

When cowlling. creates a vector naaed xxx 
with count 16-bit elaaents mattered 0-R. nO Is 
the initial value of elaaent 0, nN is the 
initial value of eleaent N, and so on. Wien 
executing, takes one erguwnt, a. off the stack 
and leaves the address of elaaent a on the suck. 

) (cowlling) 

) (executing) 

When cowlling. creates a c-vector naaed xxx 
with count »-b1t elements mat*red 0-R. bO Is 
the initial value of eleaent 0, bh is the 
Initial value of eleaent R, and to on. Wien 
executing, Ukes an argaxent, a, off the suck 
and leaves the address of elewnt a on the suck. 


Doubl* Number Extensions 


0VAR1ABLE 

xxx ( d — ) 

xxx: ( — addr ) 

At compile tlae, creates a double nuaber 
variable xxx with the initial value d. At 
run tlae, xxx leeves the address of its value 
on the stack. 

^CONSTANT 

xxx ( d — ) 

xxx:( — d ) 

At compile tiae. creates a double nuaber 
constant xxx with the initial value d. At 
run tlae, xxx leaves the value d on the stack. 

0- 

( dl d2 — d3 ) 

Leaves dl-d2«d3. 

00- 

( d - flag) 

If d is equal to 0. leaves true flag; 
otherwise, leaves false flag. 

!>■ 

( dl d2 - flag ) 

If dl equals d2. leaves true flag; otherwise, 
leaves false flag. 

00< 

( d — flag ) 

If d is negative, leaves true flag; otherwise, 
leaves false flag. 

Ik 

( dl d2 - flag ) 

If dl is less than d2, leaves true flag; other¬ 
wise, leaves false flag. 

D> 

( dl d2 - flag ) 

If dl is greater than d2, leaves true flag; 
otherwise, leaves false flag. 

OKI* 

( dl d2 — d3 ) 

Leaves the minimum of dl and d2. 

OMAX 

( dl dZ — d3 ) 

Leaves the maximum of dl and d2. 

0»R 

( d - ) 

Sends the double number at top of stack to the 
return stack. 

<K> 

( — d ) 

Pulls the double number at too of the return 
stack to the stack. 

D. 

( d - ) 

Comoiles the double number at top of stack 
into the dictionary. 

00c 

( udl ud2 — flag ) 

If the unsigned double manber udl is less 
than the unsigned double number ud2, leaves a 
true flag; otherwise, leaves a false flag. 

ft* 

< dl a — dZ ) 

Converts n to a double number and then sums 
with dl. 

High Resolution Text Output 

GCINIT 

l - ) 

Initializes the graphic character output 
routines. This must be executed prior to using 
any other hi-res output words. 

6C. 

( n — ) 

Displays the single length number n at the 
current hi-res cursor location. 

GC.R 

( nl n2 - ) 

Displays the single length number nl right- 
justified in a field n2 graphic characters 
wide. See .R . 

GCD.R 

( d n — ) 

Displays the double length number d right- 
justified in a field n graphic characters 
wide. See D.R . 

CCEMIT 

( c - ) 

Oisplays the text character c at the current 
hi-res cursor location. Three special 
characters are interpreted by GCEHIT. , 

SCLEN 

( addr n — len ) 

Scans the first n characters at addr and 
returns the number of characters that will 
actually be displayed on screen. 

GCR 

( - ) 

Repositions the hi-res cursor to the beginning 
of the next hi-res text line. See CR . 

Gas 

< - ) 

Clears the hi-res display and repositions the 
cursor in the upper lefthand corner. 

GCSPACE 

{ - ) 

Sends a space to the graphic character output 
routine. See SPACE . 

GCSPACES 

l n - ) 

Sends n spaces to the graphic character output 
routine. See SPACES . 

GCTYPE 

( eddr n — } 

Sends the first n characters at addr to the 
graphic character output routine. See TYPE . 

GC* ccc" 

( - ) 

Sends the character string ccc (delimited by ") 
to the graphic character output routine. 

GC8KS 

( - ) 

Hoves the hi-res cursor back one character 
position for overstriking or underlining. 

GCPOS 

( hon vert — ) 

Positions the hi-res cursor to the coordinates 
specified. Note that the upper lefthand corner 
is 0,0. 

GCS. 

(eddr - ) 

Sends the string found at addr and preceded by 
a count byte to the graphic character output 
routine. See $. . 

SORER 

( - ) 

Forces the graphic character output routine 
into the superscript mode (or out of the sub¬ 
script mode). See VNI below. Nay be performed 
within • string by the ♦ character. 

SUB 

( -- ) 

Forces the graphic character output routine 
into the subscript mode (or out of the super¬ 
script mode). See VNI below. Nay be performed 
within a string by the * character. 

VNI 

( " — ) 

The VNI command sets the number of eighths of 
characters to scroll up or down when either a 
SUPER or SUB command is issued. 

VKI# 

( — addr ) 

A variable set by VNI. 

OSTRIKE 

( OR or OFF - ) 

If the OSTRIKE option is ON, characters are 
printed over top of the previous characters 
giving the Impression of overstriking. 

GCBAS 

( - addr ) 

A variable which contains the address of the 
character set displayed by 6CENIT. To change 
character sets, simply store the address of 
your new character set into this variable. 

Garr 

( - addr ) 

A variable which holds the column position of 
the left margin. 

GCR6T 

( - addr ) 

A variable which holds the column position of 
the right margin. 
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April, 1982 


Notes on Starting FO RTH for the fig-Forth User 


A very popular book on the FORTH language called Starting FORTH has recently 
been published. The author, Leo Brodie, gives an excellent description of the FORT 
language as implemented at FORTH, Inc. fig-FORTH differs from that implementation 
in some areas, and this document explains those differences. All comments that 
apply to fig-FORTH also apply to valForth. 


BLANK = BLANKS (page 235) 

Brodie describes the word BLANK. In fig-FORTH, this word is BLANKS. 

EMPTY-BUFFERS vs. EMPTY-BUFFERS (page 283) 

Brodie's word EMPTY-BUFFERS does not necessarily change the buffers. In fia- 
FORTH, EMPTY-BUFFERS zero fills the buffers. 

CONTEXT vs. CONTEXT (page 247) 

These two words are not synonymous in the two versions. fig-FORTH uses a 
system of VOC-LINKS with CONTEXT, while FORTH, Inc. does not. 

EXIT = ;S (page 246) 

The word EXIT, as Brodie describes it, is identical in function to ;S in fi"- 
FORTH. 

'S = SP@ (page 247) 

The word 'S in FORTH, Inc.'s is SP@ in fig-FORTH. 

EMPTY (page 34) 

Not yet implemented in fig-FORTH. 

WIPE vs. CLEAR (page 84) 

CLEAR requires a screen number while WIPE clears the last screen edited. 
ABORT" (page 103) 

Not implemented in fig-FORTH. 


PROVIDED THROUGH THE COURTESY OF VALPAR INTERNATIONAL CORPORATION; 3801 East 34th St 
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- -DUP (page 103) 

The word ?DUP in FORTH, Inc.'s is -DUP in fig-FORTH. 


?STACK vs. ?STACK (page 103) 

LSTACK as described by Brodie as incorrect for fig-FORTH. 7STACK in fig- 
FORTH automatically aborts if there is a stack error. 


NEGATE = MINUS, DNEGATE = DMINUS (pages 123, 178) 

The words NEGATE and DNEGATE in FORTH, Inc.'s are MINUS and DMINUS respecti 
in fig-FORTH. 


+L00P vs. +LC0P (page 143) 



word +L00P, as Brodie describes it, works differently for negative 
+LQ0P in fig-FORTH. fig-FORTH always ends if the index equals the 1 
negative stepping. 



PAGE = CIS (page 143) 

Brodie's PAGE is called CLS in valForth. It has no equivalent in fig-FORTH 

IV •■■*00 = U/ (page 177) 

Brodie's U/MOD is U/ in fig-FORTH. 


CREATE vs. CREATE (page 209) 

Brodie's CREATE works differently from CREATE in fig-FORTH. A word using C 
in fig-FORTH must unSMUDGE the header before the word can be used. The unsm 
headers automatically. In addition, Brodie's CREATE and fig-FORTH CREATE move i 
default values in the CFA of the created header (see below). 


CREATE = <BUILDS (page 209) 

In Brodie's chapter 11 on extending the compiler, he uses the series CREATE 
D0ES>. In fig-FORTH, this should be <BUILDS...D0ES>. 


NUMBER vs. NUMBER (page 285) 

Brodie's NUMBER only converts numbers to double length if the double word 
is loaded. fig-FORTH always converts numbers to double length. 


PRO vI FED THROUGH THE COURTESY OF VALPAR INTERNATIONAL CORPORATION; 3301 East 341 
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= i:i, H = DP (page 247} 

The variable >IN and H in Brodie's FORTH are IN and DP respectively in 


**. 


ABLE vs. VARIABLE (page 209) 

The word VARIABLE, as Brodie describes it, accepts no value from the stack. 
FORTH, on the other hand, does expect an initialization value from the stack. 

. ' (page 215) 

These words are not synonymous. 1 in Brodie is the same as ' 2- in fig-FORTH 
more properly, ' CFA). 
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STROLLING THROUGH valFORTH 1.1 


Welcome. For this excursion you'll need an ATARI 800 (or 400) with at least 
24K, a disk drive, monitor, a printer, and valFORTH 1.1. You could even do 
without the printer. Please get everything up and running, and boot 
valFORTH. 

(To boot the disk, turn the drive(s) on and the computer off. Insert the disk 
in drive 1 and turn the computer on. The disk should now be booting, and the 
monitor speaker should be going beep-beep-beep-beep as valFORTH loads.) 

ERRORS, RECOVERIES, CRASHES 

Before we get started, let's mention the inevitable: Most of the time when 
you make an error you'll receive one of the fairly lucid fig-Forth error 
messages. If you just get a number, this will probably refer to the Atari 
error message list which you can find in the documentation that came with your 
computer. Since the Atari is a rather complex beast, you may sometimes get 
into a tangle that looks worse than it is. Keep your head. If you have party- 
color trash on the screen, for instance, and yet you can still hear the 
"peek-peek-peek" of the key when you hit return, you may have merely blown 
the display list without hurting your system. Try Shift-Clear followed by 
0 GR. . Very often you're home again. If this doesn't work, try a warm start: 
Hold down a CONSOLE button, say START, and while you've got it down, press 
SYSTEM RESET and hold both for a moment until the "valFORTH" title comes up. 

(If you were to push the SYSTEM RESET button alone, you'd get a cold start, 
which takes you back to just the protected dictionary.) A warm start gets 
you back to the "ok" prompt without forgetting your dictionary additions. 

If warm start doesn't work, your system is being kept alive only by those 
wires connected to it; it no longer has a life of its own. The standard 
procedure now is to push SYSTEM RESET alone a few times (cold start) in a 
superstitious manner, and then reboot the system. 

Look carefully at the code that blew the system last time. If you're really 
having trouble debugging, sprinkle a bunch of WAIT's and/or .S's (Stack 
Printouts) through the code, and go through again. The best thing about those 
first few long debugging sessions in any computer language is that they teach 
you the value of writing code carefully. 


VC 
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FORMATTING AND COPYING DISKS 

You may have noticed that your system came up in a green screen. In a little 
while you'll be able to change it to anything you like. We'll get to that in 
a moment, but right now type 170 LIST (and then hit RETURN.) Behold the table 
of contents. Our first priority should be to make a working disk by copying 
the original. 

Let's assume that you have a blank, unformatted disk on which to make your 
copy. Notice the line called FORMATTER on screen 170. At the right side of 
this line is probably 92 LOAD, though the number may be different in later 
releases. Type 92 LOAD (or whatever the number is) and wait until the machine 
comes back with "ok". Now you're going to type FORMAT, but for safety's 
sake why not remove the valFORTH disk and insert the blank disk? One never 
knows if newly purchased software will give you warnings before taking action. 
("Warnings" or "Prompts" make a system more friendly.) Ok, now type FORMAT. 

For the drive number you probably want to hit "1", unless you've got more 
than one drive and don't want to format on the lowest. In answer to the next 
prompt, hit RETURN unless you've changed your mind. Now wait while the machine 
does the job. If you get back "Format OK" you're in business. (If "Format 
Error" comes back, suspect a bad blank disk or drive.) You might as well 
format another disk at this time on which to store your programs. 

Now to make the copy. Return the valFORTH disk to the drive and do 170 LIST 
again. Find DISK COPIERS and do 72 LOAD, or whatever number is indicated. 

When the "ok" prompt comes back, two different disk copying routines are 
loaded: DISKC0PY1 for single drive systems and DISKC0PY2 for multiple 
drive systems. Type whichever of these words is appropriate and follow the 
instructions, ("source" means the disk you want to copy, "dest." is the 
blank "destination" disk.) There are 720 sectors that have to be copied. 

Since this can't be done in one pass, if you are using DISKC0PY1 you will 
have to swap the disks back and forth until you're done. (The computer will 
tell you when.) The less memory you have, the more passes; there is great 
benefit in having 48K. If you have more than one drive, it still takes 
several internal passes, but there is no swapping required. Either way, the 
process takes several minutes with standard Atari disk drives. 
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Nice going. Now store the original disk in some safe place. Don't write 
protect your copy yet* First we'll adjust the screen color to your taste. 

Just to see if you really have a good copy, boot it. This can be done by 
the usual on-off method, or by typing BOOT. 

COLORS 

Before playing with the colors, let's look at something else. Type VLIST, 
and watch the words go by. These are all of the commands that are currently 
in the "dictionary" in memory in your system. You can cause this listing, or 
any other, to pause by hitting CTRL and 1 at the same time. This is a handy 
feature of the Atari. The listing is restarted with the next CTRL 1. 
Additionally, in valFORTH most listings may be aborted by pressing any of the 
three yellow buttons START, SELECT, and OPTION. These three buttons together 
will be referred to as the CONSOLE. 

Do VLIST again, and abort it with a CONSOLE press after a few lines. At the 
top of the list you should see the word TASK. Remember that for a moment. 

Do 170 LIST again. Look over the list and find COLOR COMMANDS, and LOAD as 
appropriate. Now do VLIST again, and stop the list when it takes up about 
half of the screen. Above TASK you now can see a number of new commands, or 
"words" as they are commonly called in Forth. These were added to the 
dictionary by the LOAD command. Here's what some of these words do: 

Type BLUE 12 B00TC0L0R, and you get a new display color. Try BLUE 2 B00TC0L0R. 
If you try this action with the number as 4, the letters will disappear, and 
you'll have to type carefully to get them back. The number is the luminance 
or "lum" and is an even number in the range 0 to 14. The color-name is called 
the "hue." The word "color" will be used to refer to a particular combination 
of hue and lum; hence PINK 6 is a color, PINK is a hue. There are 16 hues 
available and you can read their names from the display, starting with LTORNG 
('light orange") and ending with GREY. (The hues may not match their names on 
your.monitor. Later on you'll be able to change the names to your liking, or 
eliminate them altogether to save memory, and just use numbers. For instance, 
PINK is equal to 4.) 

Try out different colors using B00TC0L0R, until you find one you can live with 
for a while. We.usually use GREEN 10 or GREEN 12 in-house at Valpar. While 
you are doing this you'll probably make at least one mistake, and the machine 
wi11 .. re Pl y with an error message like "stack empty." Just hit return to get 
the "ok" back and start whatever you were doing again. Actually, you don't 
even have to get the "ok" back, but it's reassuring to see it there. When 
you've got a color you like, do VLIST again. Note the first word above TASK. 

It should be GREY. Carefully type FORGET GREY, and do VLIST again. Notice 
that GREY and all words above it are indeed forgotten. That's just what we 
want. Now type SAVE. You'll get a (Y/N) prompt back to give you a chance to 
change your mind, since SAVE involves a significant amount of writing to 
drive #1. For practice, check to see that you still have the copy in drive 
one, and if it is there, hit Y, and off we go. When "ok" comes back, remove 
the disk and apply a write protect tab to it. Boot this disk again to see 
that it will come up in your selected color. 
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DEBUGGING 

Look at 170 again. Load the DEBUGGING AIDS, and type ON STACK. You'll see that 
the stack is empty. Great, what's a stack? The best answer to this is to 
suggest that you read Leo Brodie's book. Starting FORTH . This amusing and 
thorough treatment of FORTH starts from the novice level and continues on to 
most of the advanced concepts in FORTH. Starting FORTH is available from many 
sources, including Valpar International. Included with your valFORTH package 
is a document called "Notes on Starting FORTH for the fig-FORTH User" which 
pinpoints differences between Brodie’s dialect of FORTH, called 79 Standard, 
and the somewhat more common fig-FORTH on which valFORTH was based. 

It is not feasible to present a course on FORTH in these pages, since FORTH 
is far more powerful than BASIC, which itself requires a fair amount of space 
to present. However, we'll try to be as considerate as possible to the FORTH- 
innocent. 

The visible stack is a very good debugging and practice tool. Type 
a few integers, say 5 324 -19 0 and hit RETURN. The numbers are now 
visible on the stack. Top of stack, TOS, is at right. Print the top entry 
by typing " . " and then do DUP. Note that there are now two -19's on top. 

Do " * " to multiply them together. Now do DROP to discard the product, 361, 
currently at TOS. Ok, now do SWAP to exchange the 324 and 5 and then do " / " 
to divide 324 by 5. This should leave 64, since the answer is truncated. Now 
type 1000 * and notice that instead of getting 64000 you get -1536. This 
is of course two's complement on a two-byte number. Type U.S which will 
switch the visible stack to unsigned representation. Type .S to go back. 

The words .S and U.S may be used with the visible stack on or off to show 
the stack one time. Now type OFF STACK. Type in a few more numbers, say 
1234567. ON STACK again, and observe that the entries are retained. 

Do OVER to bring a copy of the 6 over the 7. Now DROP it. Do ROT to rotate 
the third from top, 5, to the top. Now do <R0T to put it back. In addition 
to all of these normal routines, valFORTH supports PICK and ROLL both coded 
in 6502 for speed. Notice that the 5th on stack is a 3. 5 PICK will bring a 
copy of it to TOS. Do this and then DROP the 3. Do 5 ROLL to pull the 3 
out of the stack and place it at TOS. DO SP! to clear the stack. 
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One point about number bases: Right now you're in DECIMAL. By typinq i 
HEX you go into hexadecimal, and typing DECIMAL or its abbreviation DCX ’ 
you get back. And, as usual, virtually any base may be used by typing N BASE ! 
where N is the base yOu want. Thus, 2 BASE ! gives binary, etc. Some errors, 
particularly during loading, may leave you in an unexpected base, like base 0, 
for instance. If you find the machine acting normally except for numbers, this 
may.have happened. A simple DCX will get you back to decimal. The word B? 
will print the current base in decimal. Put 30 on the stack and then do HEX. 

Now do B?. Do DCX to return to decimal. 

While we're on the subject of numbers, do ON and note that it is just a CONSTANT 
equal to 1. Similarly, do OFF and see that it is zero. Try 0 STACK and then 
1 STACK. The words ON and OFF are provided to enhance readability of code, 
but could be substituted by 1 and 0 if desired. The two representations are 
equally fast. 

We mention to the newcomer to FORTH that the stack takes the place of dummy 
variables or dummy parameters in other languages. This reduces memory overhead 
in several ways but does exact a penalty of reduced readability of FORTH source 
code. Consistent and sensible source code formatting can significantly enhance 
readability. The source code on the present disk may be used as a reasonably 
good example of well-arranged code. 



Now a few words about DECOMP. Clear the stack. Type in 3 and 4. Do 
OVER OVER followed by 2DUP and notice that these two phrases have the same 
effect. Clear the stack and then turn it off if you like, and do DECOMP 2DUP. 
What you see is a decompilation of 2DUP which indicates that it is indeed 
defined as OVER OVER. Decomp OVER. The word "primitive" in the decompilation 
of OVER indicates that OVER is defined in machine code. 

Decomp LITERAL. The word (IMMEDIATE) after LITERAL in the decompilation 
indicates that LITERAL is immediate. Not all words can be decompiled by 
DECOMP, and sometimes trash will be printed with long pauses between lines. 

In this case, hold down any CONSOLE button (the three yellow ones, remember) 
until the "ok" comes back. This may take several seconds, but rarely much 
longer. 



PRINTING 


If you have a printer attached, we can generate some hardcopy. Look at screen 
170 again. You can see the line labeled PRINTER UTILITIES. Don't load it, 
though. The printer utilities were loaded automatically when you loaded the 
debugging aids, and so are in the dictionary already. (There is no need to 
have them in twice, though it wouldn’t hurt.) You have access to the words P:, 
S:, LISTS, PLISTS, PLIST, and a couple of others relating to output. Do VLIST 
and see if you can spot this group. As a matter of fact, do ON P: VLIST OFF 
P: all in one shot. ON P: is used to route output to the printer or not. 

OFF P: stops sending to the printer. Try ON P: OFF S: 170 LIST CR OFF P: ON S: 
and notice that this time text is not sent to the display screen, only to the 
printer. That's because of OFF S: . 

Look at screen 170 again, either on display or in hardcopy, and note which 
screen the printer utilities start. Type this number in, but don't type load. 
Instead, after the number, type 10 PLISTS. This prints 10 screens starting 
from the first screen you just typed in. If you have a reasonably smart 
printer, it will automatically paginate, so that the screens are printed 
three to a page. If the printer acts peculiarly after printing each third 
screen, the pagination code in the word EJECT is probably not right for your 
printer. You'll be able to change this later on. 

Now type 30 150 LISTS and after a few blank screens you'll see the entire disk 
go by, except for the boot code. You can pause any time by CTRL 1 or stop 
by holding a CONSOLE button. 

Finally, do ON P: 30 179 INDEX OFF P: to print a disk index. The index is 
made up of the first line of each screen. 



Two editors have been included in this package. The fig (Forth Interest Group) 
Editor and the valFORTH 1.0 Editor. The latter, while a perfectly useable 
video-display editor in its own right, is actually a stripped-down version of 
the valFORTH 1.1 Editor, available with the Utilities/Editor package from Valpar 
International. The 1.0 Editor is provided to give the user some idea of what 
the very powerful 1.1 Editor is like, without actually providing it. (Among 
other things, the 1.1 Editor has a user-definable line buffer of up to 320 lines 
with a 5 line visible window at the bottom of the display. This window can be 
seen at the bottom of the 1.0 Editor, but is inactive.) 
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The fig Editor is a general-purpose FORTH line editor, and was the FORTH editing 
workhorse until good video-displays were developed. 

n 

The fig Editor User Manual is located just after this section. It is based 
on that by Bill Stoddart of FIG, United Kingdom, published in the fig-Forth 
installation manual 10/80, and is provided through the courtesy of the FORTH 
INTEREST GROUP, P.0. Box 1105, San Carlos, CA 94070. Serious Forth programmers 
should write FIG to request their catalog sheet of references and publications. 

Let's look at the valFORTH editor 1.0. Refer to the directory again, screen 170, 
and load the valFORTH editor. (Don't load the fig Editor by mistake.) Before 
proceeding, make sure that the write-protect tab on your disk is secure. The 
word to enter the editor at the screen on top of stack is V. You can remember 
it by thinking of it as "view." Type 170 V. Screen 170 is now on the display 
again, but in the valFORTH 1.0 Editor rather than as a listing. This Editor 
is a subset of the valFORTH 1.1 Editor available in the Editor/Utilities package, 
which is MUCH more powerful and convenient, and is priced far lower than any 
comparable product of which we are aware. The Editor Command card provided 
shows all of the commands available with the 1.1 Editor. Commands available 
with the 1.0 Editor are marked with asterisks (*) on the card. Let's run 
through them: 

The cursor can be moved as in the Atari "MEMO PAD" mode. That is, hold down 
the control key (CTRL) and move the cursor around the display with the four 
arrow keys. To enter text (replace mode only in 1.0), position the cursor and 
type it in. Delete characters with the backspace key as usual. The cursor 
will wrap to the next line at the end of a line, and to the top of the screen 
when it goes off the bottom. You can type at will on this screen since we 
won't save the changes to disk. 

Do a Shift-Insert and notice that a blank line is inserted at the cursor line. 

The bottom line is lost, though it is recoverable in the 1.1 version. Now do 
Shift Delete to remove a line. (Delete is on the Backspace key). These are 
all of the Editing commands available in the 1.0 Editor. There are two methods 
of exiting the editor, CTRL S and CTRL Q. CTRL S marks the screen for saving 
to disk, and CTRL Q forgets the latest set of editing changes. As usual, 
changes are not saved immediately. This is accomplished with the word FLUSH 
or by bringing other screens into the buffers and pushing the edited ones out. 
Again, as usual, the EMPTY-BUFFERS command, or its valFORTH abbreviation, MTB, 
will clear all buffers, thus forgetting any changes that have not yet been 
written to disk. 

Try CTRL Q to exit now. Reedit the screen by typing L. L does not require an 
argument on stack and will bring the last-editing screen into the editor. The 
words CLEAR and COPY have their normal meanings, as does WHERE, which has had 
the standard fig bug fixed. See the glossary for details. Note that since 
COPY in valFORTH does not FLUSH its changes, careful use allows transfers 
of single screens between disks by swapping disks after COPY and before 
FLUSH. This is particularly handy, for example, for transferring error 
message screens 176-179 between disks. 



You can make this transfer by doing 


176 176 COPY 177 177-COPY 178 178 COPY 179 179 COPY 

and then swapping in the destination disk and typing FLUSH. You may want 
to define a word to do this automatically: 

: ERRXFR ( — ) 

CR Insert source and press START" WAIT 

180 176 
DO I I COPY 
LOOP 

CR Insert dest. and press START" WAIT 
FLUSH ; 

Because there are four 512 character screen buffers in memory in valFORTH, 
four 512 characters screens at a time is the maximum for this method. 

Bulk screen moves on a single disk or between disks are available with 
the Utilities/Editor Package. 


Note: The word "screen" in Forth refers to an area of the disk. When you 

do 170 LIST you are listing screen 170. In valFORTH there are 180 screens, 

numbered 0-179, on the disk in drive 1. In multiple-drive systems screen 

numbers continue across drives, so that screens 180-349 are on drive 2. 

180 LIST will automatically read from drive 2. For technical reasons screen 0 
should not be used for program code. 

Whichever editor you use for the moment, you can write your programs to a 
blank disk and load them from there. Remember that in fig-FORTH (and so 
also in valFORTH), if you wish to continue loading from one screen to the 
next, all but the last screen should end in —>. You'll see this all through 
the valFORTH 1.1 code. You'll also see ==>. For present purposes you can 
use —> everywhere, and forget about ==>. ==> is actually a "smart" version 

of --> that does nothing if the system uses 1024 character screens instead of 
512. 

If you are a F0RTHER, and wish to use 1024 byte screens, do FULLK. To return 
to 512 character screens, do HALFK. (A working disk may be SAVE'd in either 
condition.) Note that the valFORTH 1.0 Editor will not edit 1024 character 
screens, though the 1.1 version will, and includes special IK notation. In 
the same vein, the word KL0AD that appears in the source code is a smart load. 
See the Glossary for details. 

To terminate loading one simply omits the —> on the last screen. ;S may be 
used to end loading at any point. Also note that valFORTH —> and ==> are 
smart in the sense that if you wish to stop loading before the machine is 
ready to stop, simply hold down a CONSOLE button. When —> or ==> execute, 
they first check the CONSOLE. If a button is pressed, they stop loading 
instead of continuing with the next screen. 



Before leaving editing practice, type MTB to empty the disk buffers and assure 
yourself that nothing will be flushed to disk accidentally as you read in new 
screens. Or else, do--FLUSH if you really want to save your changes. 

(Remember to remove the write-protect tab if you do.) 


r 
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GRAPHICS 

On to Graphics. Check screen 170 and load the Color Commands again, and then 
the Graphics Package.' VLIST to see what you've got, and print the list if 
you like. You may notice that GR. is not among these freshly loaded words: 

It is in the kernel, that is, the booted code. Try the following sequence: 

2 GR. (BASIC Graphics mode 2) 

5 5 POS. (Move the graphics cursor) 

G" TEST" (Send text to graphics area) 

1 COLOR (Pick a new graphics color) 

G" TEST" (More text) 

: SMPL 4 0 DO I COLOR G" TEST" LOOP ; (automate) 

SMPL SMPL SMPL (Try it out) 

: MANY BEGIN SMPL 7TERMINAL UNTIL ; (More automation) 

1 GR. (Go somewhere else) 

MANY (Press CONSOLE button to exit) 

17 GR. MANY (Try it in full screen) 

2 GR. 2 PINK 8 SE. MANY (Use SE. to change color 2) 

4 GOLD 8 SE. (Use SE. to change background color). 

0 GR. (Go back to normal text screen.) 

You can also see a quick demonstration by loading the Graphics Demo Program 
listed on screen 170. If it's not listed on screen 170, do an INDEX in the 
area of the Graphics routine screens you loaded recently. When you find the 
Graphics examples screen, load it. Then do FBOX. Take a look at the code 
and then at the Glossary to get the idea. 

As in Atari Basic, adding 16 to the graphics mode you want to enter gives 
non-split screen, and adding 32 suppresses erase-on-setup of the mode. 



1 


U 


1-9 



SOUNDS 





As a final stop on this tour, load the SOUNDS words. The word SOUND acts 
similarly to the Basic command SOUND. In valFORTH it also has the abbrevia¬ 
tion SO. and expects stack arguments like so: 

channel(0-3) frequency#(0-255) distortion(0-14 evens) volume (0-15). 

(We use "CatFish Don't Vote" as a mnemonic). 

Try, for instance 0 200 12 8 SO. and then turn it off with 0 XSND which 
just shuts off the indicated voice, 0, or XSND4 which quiets everything. 

More about sound generation by the Atari may be found in the "sound" section. 

Logical Line Input 

One of the nice features of the Atari OS is that it lets you back the cursor 
over code that you've typed in already, even edit it with various inserts, 
deletes, and retypes, and then hit return to have it reinterpreted. This 
function is supported by valFORTH, and you can re-input up to two full lines 
of text, (and a wee bit more) at a time just by moving the cursor onto the 
"logical line" you wish to re-read. Try it. 

THE GREAT SCREEN SIZE DEBATE 

The "standard" Forth screen is composed of 1024 bytes. This is a nice round 
number, and on a good text display one can have room for that many characters 
plus a few more. However, beyond tradition, there is very little functional 
reason to have 1024 byte screens over several other power-of-2 sizes. In the 
case of Atari and Apple machines, 512 byte screens make video display editors 
much easier to work with, since one can get a whole screen in the display 
at once, valFORTH supports both 1024 and 512 byte screen modes, but in-house 
at Valpar we strongly prefer 512 byte screens and recommend that you adopt 
this as your personal standard. If at any time you wish to change to IK to 
help compile software written on IK screens, you can do so with one word, 
FULLK. 



SAVING YOUR FAVORITE SYSTEM(S) 


Well, you've seen many of the bells and whistles of valFORTH. When you are 
using the language for software development you will probably have a favorite 
set of capabilities that you always want aboard. Rather than loading them 
from scratch each time, why not SAVE them to a formatted disk? Just get 
everything you want into the dictionary. After it's all loaded, put a 
formatted disk into drive 1 and type SAVE. Answer the prompt by pressing "Y" 
unless you have changed your mind, and the computer will save a bootable copy 
of your system dictionary on the blank disk. 

DISTRIBUTING YOUR PROGRAMS 

If you have a program you wish to distribute, there are two ways in which to 
proceed: 

(1) Make a PROTECTED auto-booting copy of your software by using the 

word AUTO as detailed in the "compiling Auto-Booting Software" section 
of this manual. 

(2) Make a TARGET-COMPILED version of your software, using the valFORTH 
Target Compiler, scheduled for release approximately 9/82. Target 
Compilers allow production of much smaller final FORTH products by 
allowing elimination of unnecessary code, e.g., headers, compiler, 
buffers, etc. 

In addition to the above procedures, Valpar International also 
requires that the message: 

Created in whole or part using valFORTH products of 
Valpar International, Tucson, AZ 85713, USA 
Based on fig-FORTH, provided through the courtesy of 
Forth Interest Group, P.0. Box 1105, San Carlos, CA 94070 


Hope you've enjoyed the tour. Bye now. 
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valForth Glossary 


Based on the fig-Forth Glossary 
Provided through the courtesy of 
Fourth Interest Group, P.0. Box 1105, San Carlos, CA 94070 


This glossary contains all of the word definitions in Release 1.1 of valForth. 

The definitions are presented in the order of their ASCII sort. 

The first line of each entry shows a symbolic description of the action of 
the procedure on the parameter stack. The symbols indicate the order in which input 
parameters have been placed on the stack. Two dashes " indicate the execution 
point; any parameters left on the stack are listed. In this notation, the top of 
the stack is to the right. 

The symbols include: 

addr memory address 

b 8 bit byte (i.e. hi 8 bits zero) 

c 7 bit ASCII character (hi 9 bits zero) 

d 32 bit signed double integer, most significant portion with 

sign on top of stack. 

f boolean flag. 0=false, non-zero=true 

tf boolean true flag=non-zero 

ff boolean false flag=0 

n 16 bit signed integer number 

u 16 bit unsigned integer 

The capital letters on the right show definition characteristics: 

C May only be used within a colon definition. A digit indi¬ 

cates number of memory addresses used, if other than one. 

E Intended for execution only. 

L0 Level Zero definition of FORTH-78 

LI Level One definition of F0RTH-7S 

P Has precedence bit set. Will execute even when compiling, (immediate) 

U A user variable. 

V A valForth word not in fig-Forth. 

B A word adopted from Leo Brodie's Starting Forth . 

Unless otherwise noted, all references to numbers are for 16 bit signed integers. 
The high byte of 16 bit numbers is the second byte on the stack, with the sign in the 
leftmost bit. For 32 bit signed double numbers, the most significant part (with the 
sign) is on top. 

All arithmetic is implicitly 16 bit signed integer math, with error and under¬ 
flow indication unspecified. 




Pronounced "store". 


LO 


i 

! CSP 

# 


#> 


#S 


'( 


( 


) 

)( 


(.") 


n addr — 

Store 16 bits of n at address. 


Save the stack position in CSP. Used as part of the compiler 
security. 

dl — d2 LO 

Generate from a double number dl, the next ASCII character which 
is placed in an output string. Result d2 is the quotient after 
division by BASE, and is maintained for further processing. Used 
between <# and #>. See #S. Pronounced "number". 

d — addr count LO 

Terminates numeric output conversion by dropping d, leaving the text 
address and character count suitable for TYPE. Pronounced "number- 
bracket". 

dl — d2 LO 

Generates ASCII text in the text output buffer, by the use of #, 
until a zero double number d2 results. Used between <# and #>. 
Pronounced "numbers". 

— addr P.LO 

Used in the form: 

' nnnn 

Leaves the parameter field address of dictionary word nnnn: As a 
compiler directive, executes in a colon-definition to compile the 
address as a literal. If the word is not found after a search of 
CONTEXT and CURRENT, an appropriate error message is given. Pro¬ 
nounced "tick". 

V ,E,P 

Used in the form: 

'{ WORDO W0RD1 . . . WORDN )( WORDN+1 . . .WORDM ) 
which executes as follows: If WORDO is found in a search of CONTEXT 
and CURRENT, then execute W0RD1 . . . WORDM. Generally used for con¬ 
ditional compilation. Note that if no words are to be included in 
the second group, then )( and ) must be separated by at least TWO 
blanks. 


P,L0 

Used in the form: 

( cccc) 

Ignore a comment that will be delimited by a right parenthesis on 
the same line. May occur during execution or in a colon-definition. 
A blank after the leading parenthesis is required. 


No operation. Used in '( constructs. 


V.E.P 


V,E,P 

Scans text input pointer past ")". Used in '( constructs. 

— C+ 

The run-time procedure, compiled by ." which transmits the following 
in-line text to the selected output device. See ." 


V-l 



(/LOOP) 


B,C2 


n — 

Execution time code of /LOOP. 


(;C0DE) 

(+L00P) 

(ABORT) 

(DO) 

(FIND) 

(FMT) 

(LINE) 

(LOOP) 

(NUMBER) 

(SAVE) 

* 

*/ 


C 

The run-time procedure, compiled by ;CODE, that rewrites the code 
field of the most recently defined word to point to the following 
machine code sequence. See ;C0DE. 

n C2 

The run-time procedure compiled by +L00P, which increments the loop 
index by n and tests for loop completion. See +L00P. 


Executes after an error when WARNING is -1. This word normally exe¬ 
cutes ABORT, but may be altered (with care) to a user's alternative 
procedure. 

C 

The run-time procedure compiled by DO which moves the loop control 
parameters to the return stack. See DO. 

addrl addr2 — pfa b tf (ok) 

addrl addr2 -- ff (bad) 

Searches the dictionary starting at the name field address addr2, 
matching to the text at addrl. Returns parameter field address, 
length byte of name field and boolean true for a good match. If no 
match is found, only a boolean false is left. 


nl — n2 V 

Formats disk in drive nl. Leaves 1 for good format, otherwise error 
number. Note: Because of what appears to be an OS peculiarity, this 
operation must not be the first disk access after a boot. 

nl n2 — addr count 

Convert the line number nl and the screen n2 to the disc buffer address 
containing the data. 


C2 

The run-time procedure compiled by LOOP which increments the loop 
index and tests for loop completion. See LOOP. 

dl addrl — d2 addr2 

Convert the ASCII text beginning at addrl+1 with regard to BASE. 

The new value is accumulated into double number dl, being left as d2. 
Addr2 is the address of the first unconvertible digit. Used by NUMBER. 

V 

Used by SAVE, not generally used in programs. Sets up various 
parameters preparatory to writing a bootable disk. 

nl n2 — prod LO 

Leave the signed product of two signed numbers. Pronounced "star". 

nl n2 n3 — n4 LO 

Leave the ratio n4 = nl*n2/n3 where all are signed numbers. Retention 
of an intermediate 31 bit product permits greater accuracy than would 
be available with the sequence: 

nl n2 * n3 / 

Pronounced "star-slash". 



★/MOD nl n2 n3 — n4 r;5 LO 

Leave the quotient n5 and remainder n4 of the operation nl*n2/n3. 

A 31 bit intermediate product is used as for */. Pronounced "star 
slash-mod". 

+ nl n2 — sum LO 

Leave the sum nl+n2. 

+ ! n addr — LO 

Add n to the value at the address. Pronounced "plus-store". 


+- 


+BUF 


+L00P 



+0RIGIN 


—> 


-DISK 


nl n2 — n3 

Apply the sign of n2 to nl, which is left as n3. 
add! — addr2 f 

Advance the disc buffer address addrl to the address of the next 
buffer addr2. Boolean f is false when addr2 is the buffer presently 
pointed to by variable PREV. 

nl — (run) 

addr n2 — (compile) P,C2,L0 

Used in a colon-definition in the form: 

DO ... nl +L00P 

At run-time, +L00P selectively controls branching back to the corres¬ 
ponding DO based on nl, the loop index and the loop limit. The signed 
increment nl is added to the index and the total compared to the limit. 
The branch back to DO occurs until the new index is equal to or greater , 
than the limit (nl>0), or until the new index is equal to or less that 
the limit (nl<0). Upon exiting the loop, the parameters are discarded 
and execution continues ahead. 

At compile time, +L00P compiles the run-time word (+L00P) and the branch 
offset computed from HERE to the address left on the stack by DO. 
n2 is used for compile time error checking. 

n -- addr 

Leave the memory address relative by n to the origin parameter area, 
n is the minimum address unit, either byte or word. This definition 
is used to access or modify the boot-up parameters at the origin area. 


Store n into the next available dictionary memory cell, advancing the 
dictionary pointer, (comma) 


nl n2 — diff 

Leave the difference of nl-n2. 

LO 

Continue interpretation with the next disc screen, 
screen". 

P,L0 

Pronounced "next 


addr n2 n3 flag -- n4 V 

Used by,R/W. Not generally used in programs. This word performs a 
single-sector read or write on a disk. Addr is the starting RAM 
address, n2 is the sector number (1-720), n3 is the drive number 
(1-4), and the flag is 1 for read and 0 for write. On return, n4 
will be zero if there were no problems, or it will be a DOS error 
number if a DOS error occurred. 
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-DUP 

-FIND 

-TRAILING 


.LINE 

.R 

/ 

/LOOP 


nl — nl (if zero) 

nl — nl nl (non-zero) LC> 

Reproduce nl only if it is non-zero. This is usually used to copy a 
value just before IF, to eliminate the need for an ELSE part to drop 
it. 


— pfa b tf (found) 

ff (not found) 

Accepts the next text word (delimited by blanks) in the input stream 
to HERE, and searches the CONTEXT and then CURRENT vocabularies for 
a matching entry. If found, the dictionary entry's parameter field 
address, its length byte, and a boolean true are left. Otherwise, 
only a boolean false is left. 

addr nl — addr n2 

Adjusts the character count nl of a te*t string beginning address to 
suppress the output of trailing blanks, i.e. the characters at 
addr+nl to addr+n2 are blanks. 

n - LO 

Print a number from a signed 16 bit two's complement value, converted 
according to the numeric BASE. A trailing blanks follows. Pronounced 
"dot". 


P,L0 

Used in the form: 

." cccc" 

Compiles an in-line string cccc (delimited by the trailing ") with an 
execution procedure to transmit the text to the selected output device. 
If executed outside a definition, ." will immediately print the text 
until the final The maximum number of characters may be an installa¬ 
tion dependent value. See (."). 

line scr — 

Print on the terminal device, a line of text from the disc by its line 
and screen number. Trailing blanks are suppressed. 

nl n2 -- 

Print the number nl right aligned in a field whose width is n2. No 
following blank is printed. 

nl n2 -- -quot LO 

Leave the signed quotient of nl/n2. 

n — B,C2 

Like +L00P, but uses an unsigned limit, index, and increment. Thus 
loop index may pass $7FFF without mishap. Faster than +L00P and may 
be used instead of +L00P if increment is positive (and index doesn't 
cross $7FFF.) 

nl n2 — rem quot LO 

Leave the remainder and signed quotient of nl/n2. The remainder has 
the sign of the dividend. 


/MOD 



vr 


0 12 3 


0 # 


0 < 


0 = 


0 > 


OBRANCH 


1 + 

1 - 

2 * 

2 + 

2 - 

2 / 

2 DROP 

2DUP 

20VER 

2R0T 

2 SWAP 


— n 

These small numbers are used so often that it is attractive to define 
them by name in the dictionary as constants. 

n — flag V 

Leaves a true flag if n is not equal to 0. Otherwise, leaves a false 
flag. Pronounced "zero not equal". 

n - f LO 

Leave a true flag if the number is less than zero (negative), otherwise 
leave a false flag. 

n — f LO 

Leave a true flag if the number is equal to zero, otherwise leave a 
false flag. 

n — flag V 

Leaves a true flag if n is greater than 0. Otherwise leaves a false 
flag. 

f — C2 

The run-time procedure to conditionally branch. If f is false (zero), 
the following in-line parameter is added to the interpretive pointer 
to branch ahead or back. Compiled by IF, UNTIL, and WHILE. 


LI 

B 

B 


nl — n2 

Increment nl by 1. 

nl — n2 

Subtract one from nl. Pronounced "one-minus", 
nl — n2 

Multiply nl by two. Pronounced "two-star" or "two-times", 
nl — n2 

Leave nl incremented by 2. 
nl — n2 

Leave nl decremented by 2. 
nl — n2 

Divide nl by two. Pronounced "two-slash", 
d — 

Drops the double number at TOS. 
d — d d 

Copies double number at TOS. 

d2 dl — d2 dl d2 

Copies double number at 20S to TOS. 

d3 d2 dl — d2 dl d3 V 

Moves double number at 30S over two double numbers on 20S and TOS. 

d2 dl — dl d2 B 

Exchanges double numbers at TOS and 20S. 


B 

B 

B 

B 
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P,E, LO 


Used in the form called a colon-definition: 

: cccc ; 

Creates a dictionary entry defining cccc as equivalent to the follow¬ 
ing sequence of Forth word definitions until the next or 

';C0DE'. The compiling process is done by the text interpreter as long 
as STATE is non-zero. Other details are that the CONTEXT vocabulary 
is set to the CURRENT vocabulary and that words with the precedence 
bit set (P) are executed rather than being compiled. 


;C0DE 


;S 


<# 


<= 


o 


P,C,L0 

Terminate a colon-definition and stop further compilation. Compiles 
the run-time ;S. 


Used in the fonrn: 

: cccc .... ;C0DE assembly mnemonics 


P,C,L0 


Stop compilation and terminate a new defining word cccc by compiling 
(;C0DE). Set the CONTEXT vocabulary to Assember, assembling to machine 
code the following mnemonics. 


When cccc later executes in the form: 
cccc nnnn 

the word nnnn will be created with its execution procedure given by 
the machine code following cccc. That is, when nnnn is executed, it 
does so by jumping to the code after nnnn. An existing defining word 
must exist in cccc prior to ;C0DE. 


P,L0 

Stop interpretation of a screen. ;S is also the run-time word com¬ 
piled at the end of a colon-definition which returns execution to the 
calling procedure. 

nl n2 — f LO 

Leave a true flag if nl is less than n2; otherwise leave a false 
flag. 



LO 

Set-up for pictured numeric output formatting using the words: 

<# # #S SIGN #> 

The conversion is done on a double number producing text at PAD. 
Pronounced "Bracket Number". 


n2 nl — flag V 

Leaves true flag if n2 is less than or equal to nl. Otherwise, leaves 
false flag. 

n2 nl — flag V 

Leaves true flag if n2 and nl are unequal. Otherwise, leaves false 
flag. 
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<BUILDS 


C,LO 


==> 


> 


>= 


>R 

/ 


? 


? 1K 

?COMP 

?CSP 


Used within a colon-definition: 

: cccc <BUILDS ... 

D0ES> ... ; 

Each time cccc is executed, <BUILDS defines a new word with a high- 
level execution procedure. Executing cccc in the form: 
cccc nnnn 

uses <BUILDS to create a dictionary entry for nnnn with a call to the 
D0ES> part for nnnn. When nnnn is later executed, it has the address 
of its parameter area on the stack and executes the words after D0ES> 
in cccc. <BUILDS and D0ES> allow run-time procedures to be written 
in high-level rather than in assembler code (as required by ;C0DE). 

nl n2 — f LO 

Leave a true flag if nl=n2; otherwise leave a false flag. 


If using 512 byte (half-K) screen, does —> otherwise, no 
action is taken. Used to chain screens in half-K format 
that will still load correctly in valFORTH full-K format. 


nl n2 — f LO 

Leave a true flag if nl is greater than n2; otherwise a false flag. 

n2 nl — flag V 

Leaves true flag if n2 is greater than or equal to nl. Otherwise, 
leaves false flag. 

n - C,L0 

Remove a number from the computation stack and place as the most access- 
able on the return stack. Use should be balanced with R> in the same 
definition. 

addr — LO 

Print the value contained at the address in free format according to 
the current base. 

— flag V 

Leaves a true flag if C/L is 64, indicating IK screens. Otherwise, 
leaves a false flag. 


Issue error message if not compiling. 


Issue error message if stack position differs from value saved in CSP. 


TERROR f n — 

Issue an error message number n, if the boolean flag is true. 


7EXEC 

r 


Issue an error message if not executing. 


?EXIT; — V.C 

Caution: Use only within a DO LOOP. Within DO LOOP, will cause exit 
at end of current loop if a CONSOLE button is depressed when 7EXIT is 
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7L0ADING 


7PAIRS 

7STACK 

7TERMINAL 

@EX 

ABORT 

ABS 

ACCEPT 

AGAIN 


executed. Will work only in the word in which the DO LOOP is defined, 
not in a word nested further down. 


Issue an error message if not loading, 
nl n2 — 

Issue an error message if nl does not equal n2. The message indicates 
that compiled conditionals do not match. 


Issue an error message if the stack is out of bounds. This definition 
may be installation dependent. 

-- b $cC 2S 

Perform a test of the terminal keyboard for actuation of a CONSOLE 
key. Leaves 0 if none actuated, leaves 1 for START, 2 for SELECT, 

4 for OPTION, and sums for combinations. 

addr — n LO 

Leave the 16 bit contents of address. 

addr -- y 

Fetches the word (presumably a code field address) at addr, and 
then causes it to execute. Used for conditional execution without 
the speed and memory loss of flags and/or case statements. Typical 
use would be AUXOP @EX where the variable AUXOP had been loaded with 
the cfa of the desired word, by ' DESIREDWORD CFA AUXOP ! . Pro¬ 
nounced "fetch-ex." 


Clear the stacks and enter the execution state. Return control to 
the operators terminal, printing a message appropriate to the instal¬ 
lation. 

n - u LO 

Leave the absolute value of n as u. 


addr count -- 

Same as EXPECT, except that ACCEPT uses the O.S. line input 
routine which allows full MEMO PAD editing functions to be 
utilized. EXPECT prevents hazards such as Shift-Clear while 
ACCEPT does not. SEE EXPECT. 


addr n — (compiling) P,C2,L0 

Used in a colon-definition in the form: 

BEGIN ... AGAIN 

At run-time, AGAIN forces execution to return to corresponding BEGIN. 
There is no effect on the stack. Execution cannot leave this loop 
(unless R> DROP is executed one level below). 

At compile time, AGAIN compiles BRANCH with an offset from HERE to 
addr. n is used for compile-time error checking. 



ALLOT 


Add the signed number to the dictionary pointer DP. May be used to 
reserve dictionary space or re-origin memory. 


AND 

B/BUF 

B/SCR 

BACK 

BASE 

BEGIN 




BL 

BLANKS 

BLK 

BLOCK 


nl n2 — n3 L0 

Leave the bitwise logical and of nl and n2 as n3. 

— n 

This constant leaves the number of bytes per disc buffer the bvte 
count read from disc by BLOCK. y 


— n 

This constant leaves the number of blocks per editing screen, 
addr — 

Calculate the backward branch offset from HERE to addr and compile 
into the next available dictionary memory address. 

addr U,L0 

A user variable containing the current number base used for input and 
output conversion. 


— addr n (compiling) 

Occurs in a colon-definition in form: 
BEGIN ... UNTIL 
BEGIN ... AGAIN 
BEGIN ... WHILE ... REPEAT 


At run-time, BEGIN marks the start of a sequence that may be repetitively 
executed. It serves as a return AGAIN or REPEAT. When executing UNTIL 

Wl11 0CCUr lf the t0P ° f the Stack is false > f ° r 
AGAIN and REPEAT a return to BEGIN always occurs. 


At compile time, BEGIN leaves its return address and n for compiler 
error checking. K 


— c 

A constant that leaves the ASCII value for "blank", 
addr count — 

Fill an area of memory beginning at addr with blanks. 

— addr U>L0 

A user variable containing the block number being interpreted. *If 
zero, input is being taken from the terminal input buffer. 

n -- addr I_q 

Leave the memory address of the block buffer containing block n. If 
the block is not already in memory, it is transferred from disc to 
which ever buffer was least recently written. If the block occupying 
that buffer has been marked as up-dated, it is rewritten to disc before 
block n is read into the buffer. See also BUFFER, R/W UPDATE FLUSH 
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BOOT 

BRANCH 


BUFFER 


C! 


C, 


V 

Boots disk in drive 1. .Same effect as turning computer on and off. 

C2,L0 

The run-time procedure to unconditionally branch. An in-line offset 
is added to the interpretive pointer IP to branch ahead or back. 
BRANCH is compiled by ELSE, AGAIN, REPEAT. 

n — addr 

Obtain the next memory buffer, assigning it to block n. If the con¬ 
tents of the buffer is marked as updated, it is written to the disc. 
The block is not read from the disc. The address left is the first 
byte within the buffer for data storage. 

b addr — 

Store 8 bits at address. 


b — 

Store 8 bits of b into the next available dictionary byte, advancing 
the dictionary pointer. 


C/L 

- n V 

A CONSTANT equal to the number of characters per line in the ValForth 
screen. Usually 32, but may be 64 if 1024 byte screens in use. 

C? 

addr — 

Fetches a byte from addr and prints it using . . 

V 

c@ 

addr --- b 

Leave the 8 bit contents of memory address. 


CFA 

pfa — cfa 

Convert the parameter field address of a definition to its 
field address. 

code 

CMOVE 

from to count — 



Move the specified quantity of bytes beginning at address from to address 
to. The contents of address from is moved first proceeding toward 
high memory. 

COLD 

The cold start procedure to adjust the dictionary pointer to the minimum 
standard and restart via ABORT. May be called from the terminal to 
remove application programs and restart. 

COMPILE " C2 

When the word containing COMPILE executes, the execution address of 

the word following COMPILE is copied (compiled) into the dictionary. 

This allows specific compilation situations to be handled in addition 
to simply compiling an execution address (which the interpreter al- 
reac(y does). 

CONSTANT n — LO 

A defining word used in the form: 

! n CONSTANT cccc 

to create word cccc, with its parameter field containing n. When 
cccc is later executed, it will push the value of n to the stack. 
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CONTEXT 

COUNT 


CR 

CREATE 


CSAVE 


addr ' U,LO 

A user variable containing a pointer to the vocabulary within which 
dictionary searches will first begin. 

addrl — addr2 n LO 

Leave the byte address addr2 and byte count n of a message text begin¬ 
ning at address addrl. It is presumed that the first byte at addrl 
contains the text byte count and the actual text starts with the second 
byte. Typically, COUNT is followed by TYPE. 


Transmit a carriage return and line feed to the selected output device. 


A defining word used in the form: 

CREATE cccc 

by such words as CODE and CONSTANT to create a dictionary header for 
a FORTH definition. The code field contains the address of the word's 
parameter field. The new word is created in the CURRENT vocabulary. 

V 

Creates a bootable copy of RAM-resident system up to HERE on cassette. 
Computer beeps twice to indicate user must press Record and Play but¬ 
tons on recorder, prior to pressing RETURN. CSAVE expects leaderless 
tape. If your tape has a leader, wind to just before the end of leader. 


CSP 

CURRENT 


D! 

D+ 

D+- 


D. 


D.R 


DO 


— addr U 

A user variable temporarily storing the stack pointer position, for 
compilation error checking. 

— addr 

Address of a pointer to second word in the parameter field of the current 
vocabulary. (The current vocabulary is the one to which new definitions 
are added.) 

d addr -- \j 

Stores double number d into addr. 

dl d2 — dsum 

Leave the double number sum of two double numbers, 
dl n — d2 

Apply the sign of n to the double number dl, leaving it as d2. 

d — LI 

Print a signed double number from a 32 bit two's complement value. 

The high-order 16 bits are most accessable on the stack. Conversion 
is performed according to the current BASE. A blank follows. Pro¬ 
nounced "D-dot." 

d n — 

Print a signed double number d right aligned in a field n characters 
wide. 


addr — d 

Fetches double number d from addr. 


V 
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DABS 


DECIMAL 

DEFINITIONS 

DIGIT 

DLITERAL 

DMINUS 

DO 


DOES> 


d — ud 

Leave the absolute value ud of a double number. 


Set the numeric conversion BASE for decimal input-output. 


Used in the form: 

cccc DEFINITIONS 

Set the CURRENT vocabulary to the CONTEXT vocabulary. In the example, 
executing vocabulary name cccc made it the CONTEXT vocabulary and exe¬ 
cuting DEFINITIONS made both specify vocabulary cccc. 

c nl — n2 tf (ok) 
c nl — ff (bad) 

Converts the ASCII character c (using base nl) to its binary equiva¬ 
lent n2, accompanied by a true flag. If the conversion is invalid, 
leaves only a false flag. 

d -- d (executing) 

d — (compiling) p 

If compiling, compile a stack double number into a literal. Later 

execution of the definition containing the literal will push it to 

the stack. If executing, the number will remain on the stack. 

% 

dl — d2 

Convert dl to its double number two's complement, 
nl n2 — (execute) 

addr n -- (compile) P,C2;L0 

Occurs in a colon-definition in form: 

DO ... LOOP 
DO .. +L00P 

At run-time, DO begins a sequence with repetitive execution controlled 
by a loop limit nl and an index with initial value n2. DO removes 
these from the stack. Upon reaching LOOP, the index is incremented by 
one. Until the new index equals or exceeds the limit, execution loops 
back to just after DO; otherwise, the loop parameters are discarded and 
execution continues ahead. Both nl and n2 are determined at run-time 
and may be the result of other operations. Within a loop "I" will copy 
the current value of the index to the stack. See I, LOOP, +L00P, 
LEAVE. 

When compiling within the colon-definition, DO compiles (DO), leaves the 
following address addr and n for later error checking. 


LO 

A word which defines the run-time action within a high-level defining 
word. D0ES> alters the code field and first parameter of the new word 
to execute the sequence of compiled work addresses following D0ES>. 
Used in combination with <BUILDS. When the D0ES> part executes it 
begins with the address of the first parameter of the new word on the 
stack. This allows interpretation using this area or its contents. 
Typical uses include the Forth assembler, multi-dimensional arrays, 
and compiler generation. 

— addr U,L 

A user variable, the dictionary pointer, which contains the address of 
the next free memory above the dictionary. The value may be read by 
HERE and altered by ALLOT, or directly. 
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DPL 


DRO 

DR1 


DROP 

DUP 

ELSE 


EMIT 


— addr ' U,LO 

A user variable containing the number of digits to the right of the 
decimal on double integer input. It may also be used hold output column 
location of a decimal point, in user generated formatting. The default 
value on single number input is -1. 


Installation dependent commands to select disc drives, by presetting 
OFFSET. The contents of OFFSET is added to the block number in BLOCK 
to allow for this selection. Offset is supressed for error text so 
that it may always originate from drive 0. 

n — LO 

Drop the number from the stack. 

n — n n LO 

Duplicate the value on the stack. 

addrl nl — addr2 n2 (compiling) 

P,C2,L0 

Occurs within a colon-definition in the form: 

IF ... ELSE ... ENDIF 

At run-time, ELSE executes after the true part following IF. ELSE 
forces execution to skip over the following false part and resumes 
execution after the ENDIF. It has no stack effect. 

At compile-time, ELSE emplaces BRANCH reserving a branch offset, leaves 
the address addr2 and n2 for error testing. ELSE also resolves the 
pending forward branch from IF by calculating the offset from addrl 
to HERE and storing at addrl. 

c — LO 

Transmit ASCII character c to the selected output device. OUT is 
incremented for each character output. 


EMPTY-BUFFERS LO 

Mark all block-buffers as empty, not necessarily affecting the contents. 
Up-dated blocks are not written to the disc. This is also an initiali¬ 
zation procedure before first use of the disc. Alias is MTB. 

ENCLOSE addrl c — addrl nl n2 n3 

The text scanning primitive used by WORD. From the text address 
addrl and an ASCII delimiting character c, is determined the byte 
offset to the first non-delimiter character nl, the offset to the first 
delimiter after the text n2, and the offset to the first character 
not included. This procedure will not process past an ASCII "null", 
treating it as an unconditional delimiter. 

END P,C2,L0 

This is an "alias" or duplicate definition for UNTIL. 
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ENDIF 


ERASE 

ERROR 


EXECUTE 

EXPECT 

FENCE 

FILL 

FIRST 

FLD 

FORGET 


addr n — (compile) P,CO,LO 

Occurs in a colon-definition in form: 

IF ... ENDIF 

IF ... ELSE ... ENDIF 

At run-time, ENDIF serves only as the destination of a forward branch 
from IF or ELSE. It marks the conclusion of the conditional structure. 
THEN is another name for ENDIF. Both names are supported in fiq-FORTH. 
See also, IF and ELSE. 

At compile-time, ENDIF computes the forward branch offset from addr to 
HERE and stores it at addr. n is used for error tests. 

addr n — 

Clear a region of memory to zero from addr over n addresses, 
n — in blk 

Execute error notification and restart of system. WARNING is first 
examined. If 1, the text of line n, relative to screen 176 of drive 0 
is printed. This line number may be positive or negative, and beyond 
just screen 176. If WARNINGS), n is just printed as a message number 
(non disc installation). If WARNING is -1, the definition (ABORT) 
is executed, which executes the system ABORT. The user may cautiously 
modify this execution by altering (ABORT). fig-FORTH saves the contents 
of IN and BLK to assist in determining the location of the error. Final 
action is execution of QUIT. 

addr — 

Execute the definition whose code field address is on the stack. The 
code field address is also called the compilation address. 

addr count — LO 

Transfer characters from the terminal to address, until a "return" or 
the count of characters have been received. One or more nulls are 
added at the end of the text. 

-- addr U 

A user variable containing an address below which FORGETting is trapped. 
To forget below this point, the user must alter the contents of FENCE. 

addr quan b — 

Fill memory at the address with the specified quantity of bytes b. 

— addr 

A constant that leaves the address of the first (lowest) block buffer. 

-- addr U 

A user variable for control of number output field width. Presently 
unused in fig-FORTH. 


E,L0 

Executed in the form: 

FORGET cccc 

Delete definition named cccc from the dictionary with all entries 
physicalIv following it. 
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FORTH 


P,L1 

The name of the primary vocabulary. Execution makes FORTH the CONTEXT 
vocabulary. Until additional user vocabularies are defined, new user 
definitions become a part of FORTH. FORTH is immediate, so it will 
execute during the creation of a colon-definition, to select this voca¬ 
bulary at compile time. 


FULLK — V 

Sets C/L to 64 and B/SCR to 8, producing 1024 byte screen operation. 

May be SAVEd in this condition. (See HALFK) 

6FLAG — addr V 

A variable that holds a Graphics mode cursor control flag. When the 
value at GFLAG is non-zero, valForth assumes a split-screen is opera¬ 
tive, and will use the alternate cursor-address variables provided by 
the Operating System to use the text window at the bottom of the display. 

HALFK — V 

Sets C/L to 32 and B/SCR to 4. producing 512 byte screen operation. May 
be SAVEd in this condition. (See FULLK] 

HERE - addr LO 

Leave the address of the next available dictionary location. 

« 

HEX - LO 

Set the numeric conversion base to sixteen (hexadecimal). 

HLD — addr LO 

A user variable that holds the address of the latest character of 
text during numeric output conversion. 

HOLD c — LO 

Used between <# and #> to insert an ASCII character into a pictured 
numeric output string, 
e.g. 2E HOLD will place a decimal point. 

I n C,L0 

Used within a DO-LOOP to copy the loop index to the stack. Other 
use is implementation dependent. See R. 

I' - n B 

Copies the second item on the return stack to the stack. Generally 
used to get the index of the present DO LOOP after an item has been 
pushed to the return stack for convenience. 

ID. addr -- 

Print a definition's name from its name field address. 
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IMMEDIATE 

IN 

INDEX 

INTERPRET 

/ 

J 

KEY 

KLOAD 


f — (run-time) 

— addr n (compile) p j 02 LO 

Occurs in a colon-definition in form: * * ) 

IF (tp)"... ENDIF 
IF (tp) ... ELSE (fp) ... ENDIF 
At run-time, IF selects execution based on a boolean flag. If f is 
true (non-zero), execution continues ahead thru the true part. If f is 
false (zero), execution skips till just after ELSE to execute the false 
part. After either part, execution resumes after ENDIF. ELSE and its 
false part are optional.; if missing, false execution skips to just 
after ENDIF. 

At compile-time IF compiles OBRANCH and reserves space for an offset 
at addr. addr and n are used later for resolution of the offset and 
error testing. 


Mark the most recently made definition so that when encountered at 
compile time, it will be executed rather than being compiled, i.e. 
the precedence bit in its header is set. This method allows defini¬ 
tions to handle unusual compiling situations, rather than build them 
into the fundamental compiler. The user may force compilation of an 
immediate definition by preceeding it with [COMPILE] . 

— addr L() 

A user variable containing the byte offset within the current input 
text buffer (terminal or disc) from which the next text will be ac- -> 
cepted. WORD uses and moves the value of IN. 

from to — 

Print the first line of each screen over the range from, to. This is 
used to view the comment (first) lines of an area of text on disc screens 


The outer text interpreter which sequentially executes or compiles 
text from the input stream (terminal or disc) depending on STATE. If 
the word name cannot be found after a search of CONTEXT and then CURRENT 
it is converted to a number according to the current base. That also 
failing, an error message echoing the name with a " ?" will be given. 

Text input wi11 be taken according to the convention for WORD. If a 
decimal point is found as part of a number, a double number value will 
be left. The decimal point has no other purpose than to force this 
action. See NUMBER. 

- n B 

Copies the third item on the return stack to the stack. Generally 
used to get the index of the next outer DO LOOP. 

— c LO 

Leave the ASCII value of the next terminal key struck. 

screen -- V 

If C/L has a value other than 64, then the number on stack is doubled. 

In either case, LOAD is then executed. The purpose is to allow smart 
conditional loading of either IK screen or 1/2K screen formats. See '(. ) 
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LABEL 


LATEST 

LEAVE 

LFA 


cccc, 

cccc, — addr 

At compilation time, creates a word cccc.* At run time, cccc leaves 
the address of its pfa on the stack. Used to set up a pointer to the 
following area of memory, as for a machine language subroutine or a 
player image. Examples: 

Example 1: Player image 
2 BASE ! 

LABEL UPARROW 
00011000 C, 

00111100 C, 

01111110 C, 

00011000 C, 

00011000 C, 

00011000 c, 

DCX 

Example 2: Machine code two-times 
ASSEMBLER 

LABEL 2* 0 ,X ASL, 1 ,X ROL, RTS, 

— addr 

Leave the name field address of the topmost word in the CURRENT voca¬ 
bulary. 

C,L0 

Force termination of a DO-LOOP at the next opportunity by setting the 
loop limit equal to the current value of the index. The index itself 
remains unchanged, and execution proceeds normally until LOOP or +L00P 
is encountered. 

pfa — lfa 

Convert the parameter field address of a dictionary definition to its 
link field address. 
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LIMIT 

LIST 

LIT 

LITERAL 

LOAD 

LOOP 


M* 

M/ 

M/MOD 

MAX 


— n 

A constant leaving the address just above the highest memory available 
for a disc buffer. 

n - LO 

Display the ASCII text of screen n on the selected output device. 

SCR contains the screen number during and after this process. 

n . C2,L0 

Within a colon-definition, LIT is automatically compiled before each 
16 bit literal number encountered in input text. Later execution of 
LIT causes the contents of the next dictionary address to be pushed 
to the stack. 

n — (compiling) P,C2,L0 

If compiling, then compile the stack value n as a 16 bit literal. 

This definition is immediate so that it will execute during a colon 
definition. The intended use is: 

: xxx [[calculate 3 LITERAL ; 

Compilation is suspended for the compile time calculation of a value. 
Compilation is resumed and LITERAL compiles this value. 

n — LO 

Begin interpretation of screen n. Loading will terminate at the end 
of the screen or at ;S. See ;S and —>. 

addr n -- (compiling) P,C2,L0 

Occurs in a colon-definition in form: 

DO ... LOOP 

At run-time, LOOP selectively controls branching back to the correspond¬ 
ing DO based on the loop index and limit. The loop index is incremented 
by one and compared to the limit. The branch back to DO occurs until 
the index equals or exceeds the limit; at that time, the parameters are 
discarded and execution continues ahead. 

At compile-time, LOOP compiles (LOOP) and used addr to calculate an 
offset to DO. n is used for error testing. 

nl n2 — d 

A mixed magnitude math operation which leaves the double number signed 
product of two signed numbers. 

d nl — n2 n3 

A mixed magnitude math operator which leaves the signed remainder 
n2 and signed quotient n3, from a double number dividend and divisor 
nl. The remainder takes its sign from the dividend. 

udl u2 — u3 ud4 

An unsigned mixed magnitude math operation which leaves a double quo¬ 
tient ud4 and remainder u3, from a double dividend udl and single 
divisor u2. 

nl n2 -- max LO 

Leave the greater of two numbers. 
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MESSAGE 


n — 

Print on the selected output device the text of line n relative to 
screen 176 of drive 0. n may be positive or negative. MESSAGE may be 
used to prir^t incidental text such as report headers. If WARNING is 
zero, the message will simply be printed as a number (disc unavailable). 


MIN nl n2 — min L0 

Leave the smaller of two numbers. 

MINUS nl — n2 L0 

Leave the two's complement of a number. 

MOD nl n2 -- mod LO 

Leave the remainder of nl/n2, with the same sign as nl. 

MTB ~ V 

Alias of EMPTY-BUFFERS. 


NEXT — addr 

This is the inner interpreter that uses the interpretive pointer IP 
to execute compiled Forth definitions. It is not directly executed, 
but is the return point for all code procedures. It acts by fetching 
the address pointed by IP, storing this value in register W. It then 
jumps to the address pointed to by the address pointed to by W. W 
points to the code field of a definition which contains the address 
of the code which executes for that definition. This usage of in¬ 
direct threaded code is a major contributor to the power, portability, * 
and extensibility of Forth. (Assembler Vocabulary) 

NFA pfa — nfa 

Convert the parameter field address of a definition to its name field. 

NOOP — V 

A word that does nothing in minimal time. May be used for reserving 
space in a definition or as a null operation for a word that uses @EX. 
Generally for advanced programmers. Identical to TASK. Pronounced 
"no-op". 

NOT n — flag V 

Leaves a true flag if n is equal to 0. Otherwise, leaves a false flag. 

NUMBER addr — d 

Convert a character string left at addr with a preceeding count, to 
a signed double number, using the current numeric base. If a decimal 
point is encountered in the text, its position will be given in DPL, 
but no other effect occurs. If numeric conversion is not possible, 
an error message will be given. 

0+S start count -- upper-1imit+1 lower-limit V 

Same as OVER + SWAP. Used to set up limits for DO LOOPs and the like. 

OFF — 0 V 

A CONSTANT equal to 0. Used to enhance readability. 
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OFFSET 


ON 

OR 

OUT 

OVER 

PAD 

PFA 

PFLAG 

r- 

PICK 

POP 

PREV 

PROMPT 

PUSH 


-- addr U 

A user variable which may contain a block offset to disc drives. The 
contents of OFFSET is added to the stack number by BLOCK. Messages 
by MESSAGE are independent of OFFSET. See BLOCK, DRO, DR1, MESSAGE. 


— 1 V 

A CONSTANT equal to 1. Used to enhance readability. 

nl n2 -- or LO 

Leave the bit-wise logical or of two 16 bit values. 

-- addr U 

A user variable that contains a value incremented by EMIT. The user 
may alter and examine OUT to control display formatting. 

nl n2 — nl n2 nl LO 

Copy the second stack value, placing it as the new top. 

— addr LO 


Leave the address of the text output buffer, which is a fixed offset 
above HERE. 

nfa — pfa 

Convert the name field address of a compiled definition to its para¬ 
meter field address. 

— addr V 

A variable that holds an output-select value. If bit 0 is set then 
output will be sent to the display screen. If bit 1 is set, then output 
will be sent to the printer. If both bits are set, then output will 
go.to both channels. 

... n -- ... nl V 

Copies the nth entry below n on stack to top of stack. 2 PICK is the 
same as OVER, 1 PICK is the same as DUP. 

— addr 

The code sequence to remove a stack value and return to NEXT. POP is 
not directly executable, but is a Forth re-entry point after machine 
code. (Assembler Vocabulary) 

— addr 

A variable containing the address of the disc buffer most recently 
referenced. The UPDATE command marks this buffer to be later written 
to disc. 


V 

Intended for system use only, in QUIT. A smart version of the usual 
ok" in QUIT. Prevents "ok" and visible stack printout from being 
routed to printer. 

— addr 

This code sequence pushes machine registers to the computation stack 
and returns to NEXT. It is not directly executable, but is a Forth 
re-entry point after machine code. (Assembler Vocabulary) 
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PUT 


— addr 

This code sequence stores machine register contents over the topmost 
computation stack value and returns to NEXT. It is not directly execu 
table, but a Forth re-entry point after machine code. 


QUERY 


QUIT 

R 

R# 

R/W 


R> 


RO 

REPEAT 


ROLL 

ROT 

RP! 


Input 80 characters of text (or until a "return") from the operators 
terminal. Text is positioned at the address contained in TIB with IN 
set to zero. 


Clear the return stack, stop compilation, and return control to the 
operators terminal. No message is given, no "ok" 

— n 

Copy the top of the return stack to the computation stack. 

— addr U 

A user variable which may contain the location of an editing cursor, 
or other file related function. 

addr blk f - 

The fig-FORTH standard disc read-write linkage, addr specified is the 
source or destination block buffer, blk is the sequential number of 
the referenced block; and f is a flag for f=0 write and f=l read. 

R/W determines the location on mass storage, performs the read-write 
and performs any error checking. Important: See Note 1 at end of glossary. 


Remove the top value from the return stack and leave it on the compu¬ 
tation stack. See >R and R. 

-- addr U 

A user variable containing the initial location of the return stack. 
Pronounced R-zero. See RP! 

addr n — (compiling) p j C2 

Used within a colon-definition in the form: 

BEGIN ... WHILE ... REPEAT 

At run-time, REPEAT forces an unconditional branch back to just after 
the corresponding BEGIN. 

At compile-time, REPEAT compiles BRANCH and the offset from HERE to 
addr. n is used for error testing. 

• • • n * *« y 

Moves the nth entry below n on stack to top of stack. 3 ROLL is the 
same as ROT, 2 ROLL is the same as SWAP. 0 ROLL is undefined. 

nl n2 n3 n2 n3 nl L0 

Rotate the top three values on the stack, bringing the third to the 
top. 


A computer dependent procedure to initialize the return stack pointer 
from user variable RO. 
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RPICK 


S->D 

SAVE 

SO 

SCR 

SGRCTL 

SIGN 

SMUDGE 

SP! 

SP@ 

SPACE 

SPACES 

SPEMIT 


n -- V 

Copies nth entry on return stack to parameter (number) stack. For 
instance, 1 RPICK is the same as R and 2 RPICK is the same as I' 
etc. 


n — d 

Sign extend a single number to form a double number. 


V 

Gives prompt, and if answered with press of "Y" key, moves COLD and 
FENCE parameters to cover current system, makes Forth current, and 
creates a bootable copy of RAM-resident system up to HERE on disk in 
drive 1. 


— addr U 

A user variable that contains the initial value for the stack pointer. 
Pronounced S-zero. See SP! 

-- addr U 

A user variable containing the screen number most recently referenced 
by LIST. 


-- addr V 

"Shadow Register" for GRACTL, the Atari graphics control register. 

See Atari Operating System Manual for explanation. 

n d — d LO 

Stores an ASCII sign just before a converted numeric output 
string in the text output buffer when n is negative, n is discarded, 
but double number d is maintained. Must be used between <# and #>. 




Used during word definition to toggle the "smudge bit" in a definitions' 
name field. This prevents an uncompleted definition from being found 
during dictionary searches, until compiling is completed without error. 


A computer dependent procedure to initialize the stack pointer from SO. 
-- addr 

A computer dependent procedure to return the address of the stack 
position to the top of the stack, as it was before SP@ was executed, 
(e.g. 1 2 SP@ @ . . . would type 221) 


LO 

Transmit an ASCII blank to the output device. 

n — LO 

Transmit n ASCII blanks to the output device. 

C — See ~X(o V 

Like EMIT, but defined for Atari. Will output control codes as charac¬ 
ters instead of executing the controls. Used by EXPECT and other 
words. 
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STATE 


SWAP 

TASK 

THEN 

TIB 

TOGGLE 

TRAVERSE 

TRIAD 


— addr L0>u 

A user variable containing the compilation state. A non-zero value 
indicates compilation. The value itself may be implementation depen¬ 
dent. 


nl n2 „ — n2 nl 

Exchange the top two values on the stack. 


LO 


A no-operation word which can mark the boundary between applications. 
By forgetting TASK and re-compiling, an application can be discarded* 
in its entirety. 


An alias for ENDIF. 

— addr U 

A user variable containing the address of the terminal input buffer. 

addr b — 

Complement the contents of addr by the bit battern b. 
addrl n — addr2 

Move across the name field of a fig-FORTH variable length name field, 
addrl is the address of either the length byte or the last letter. 

If n=l, the motion is toward hi memory; if n=-l, the motion is toward 
low memory. The addr2 resulting is address of the other end of the 
name. 


scr — 

Display on the selected output device the three screens which include 
that numbered scr, beginning with a screen evenly divisible by three. 
Output is suitable for source text records, and includes a reference 
line at the bottom taken from line 14 of screen 177. 
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TYPE 


addr count -- I_q 

Transmit count characters from addr to the selected output device. 


U* 


U. 


U.R 


U/ 


U> 


TYPE as supplied zeroes out the high bit of each character before 
sending it to the output device, usually the screen or printer. 

If you want to be able to type all 8 bits for inverse characters, 
do the following: 

255 ' TYPE 20 + C! 

and return to 7 bit output by doing 

127 ' TYPE 20 + C! 

More generally, 

: 78TYPE < ' TYPE 14 + > C! ; 

: 7TYPE 127 78TYPE ; 

: 8 TYPE 255 78TYPE ; 

(What you are doing with all of this is changing the mask that 
TYPE uses before executing EMIT.) 


Ul U2 — Ud St< 21 

Leave the unsigned double number product of two unsigned numbers. 

n — 0 

Prints the number n in unsigned form. 

u n — B 

Prints unsigned number u right justified in a field n wide. 

Ud Ul — u2 u3 *=>C(r 27 

Leave the unsigned remainder u2 and unsigned quotient u3 from the 
unsigned double dividend ud and unsigned divisor ul. 

u 2 ul -- flag y 

Leaves true flag is u2 (unsigned) is greater than ul (unsigned). 
Otherwise, leaves false flag. 
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V 


u? 

UNTIL 

UPDATE 

USE 

USER 

VARIABLE 

VOC-LINK 

VOCABULARY 


addr — 

Does a @ from addr and an unsigned print of top of stack. 

f' — (run-time) 
addr n — (compile) P,C2,L0 

Occurs within a colon-definition in the form: 

BEGIN ... UNTIL 

At run-time, UNTIL controls the conditional branch back to the 
corresponding BEGIN. If f is false, execution returns to just after 
BEGIN; if true, execution continues ahead. 

At compile-time, UNTIL compiles (OBRANCH) and an offset from HERE to 
addr. n is used for error tests. 


LO 

Marks the most recently referenced block (pointed to by PREV) as 
altered. The block will subsequently be transferred automatically to 
disc should its buffer be required for storage of a different block. 


— addr 

A variable containing the address of the block buffer to use next, as 
the least recently written. 


n — LO 

A defining word used in the form: 
n USER cccc 

which creates a user variable cccc. The parameter field of cccc 
contains n as a fixed offset relative to the user pointer register 
UP for this user variable. When cccc is later executed, it places 
the sum of its offset and the user area base address on the stack 
as the storage address of that particular variable. 


n - E.LU 

A defining work used in the form: 
n VARIABLE cccc 

When VARIABLE is executed, it creates the definition cccc with its 
parameter field initialized to n. When cccc is later executed, the 
address of its parameter field (containing n) is left on the stack, 
so that a fetch or store may access this location. 


— addr U 

A user variable containing the address of a field in the definition of 
the most recently created vocabulary. All vocabulary names are linked 
by these fields to allow control for FORGETting thru multiple vocabu¬ 
laries. 


E,L 

A defining word used in the form: 

VOCABULARY cccc 

to create a vocabulary definition cccc. Subsequent use of cccc will 
make it the CONTEXT vocabulary which is searched first by INTERPRET. 

The sequence "cccc DEFINITIONS" will also make cccc the CURRENT voca¬ 
bulary into which new definitions are placed. 

In fig-FORTH, cccc will be so chained as to include all definitions of 
the vocabulary in which cccc is itself defined. All vocabularies ulti¬ 
mately chain to Forth. By convention, vocabulary names are to be de¬ 
clared IMMEDIATE. See VOC-LINK. 


V-25 



VLIST 


List the names of the definitions in the context vocabulary. 


WAIT 

WARNING 


WHILE 


WIDTH 

\ 


WORD 


X 


XOR 

ok 


V 

Halts execution of Forth until a CONSOLE button is pressed. 

— addr U 

A user variable containing a value controlling messages. If = 1 
disc is present, and screen 176 of drive 0 is the base location for 
messages. If = 0, no disc is present and messages will be presented 
by number. If * -1, execute (ABORT) for a user specified procedure. 
See MESSAGE, ERROR. 

f -- (run-time) 

adl nl — adl nl ad2 n2 P,C2 

Occurs in a colon-definition in the form: 

BEGIN ... WHILE (tp) ... REPEAT 
At run-time, WHILE selects conditional execution based on boolean 
flag f. If f is true (non-zero), WHILE continues execution of the 
true part thru to REPEAT, which then branches back to BEGIN. If f 
is false (zero), execution skips to just after REPEAT, exiting the 
structure. 

At compile time, WHILE emplaces (OBRANCH) and leaves ad2 of the re¬ 
served offset. The stack value will be resolved by REPEAT. 

— addr U 

In fig-FORTH, a user variable containing the maximum number of letters 
saved in the compilation of a definitions’ name. It must be 1 thru 
31, with a default value of 31. The name character count and its 
natural characters are saved, up to the value in WIDTH. The value may 
be changed at any time within the above limits. 

c — LO 

Read the next text characters from the input stream being interpreted, 
until a delimiter c is found, storing the packed character string 
beginning at the dictionary buffer HERE. WORD leaves the character 
count in the first byte, the characters, and ends with two or more 
blanks. Leading occurances of c are ignored. If BLK is zero, text 
is taken from the terminal input buffer, otherwise from the disc 
block stored in BLK. See BLK, IN. 


This is pseudonym for the "null" or dictionary entry for a name of 
one character of ASCII null. It is the execution procedure to termi¬ 
nate interpretation of a line of text from the terminal or within a 
disc buffer, as both buffers always have a null at the end. 

nl n2 — xor LI 

Leave the bit-wise logical exclusive-or of two values. 

- - ialcA. V 

Does three backspaces. When using "logical line input" from keyboard 
to re-input previously entered line, this word gives harmless meaning 
to the old "ok" prompt Forth may find in the input stream. See "logical 
line input" section in Strolling through ValForth. 
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c 


Used in a colon-definition in form: 

: xxx C words 3 more ; 

Suspend compilation. The words afterCare executed, not compiled. 
This allows calculation or compilation exceptions before resuming 
compilation with 3 . See LITERAL,3 . 


[Compile] — p,c 

Used in a colon-definition in form: 

: xxx [COMPILE] FORTH ; 

JCOMPIL0 will force the compilation of an immediate definition, that 
would otherwise execute during compilation. The above example will 
select the FORTH vocabulary when xxx executes, rather than at compile 
time. 


3 


LI 

Resume compilation, to the completion of a colon-definition. See [. 



NOTES: 

Note 1 

Due to a bug in at least some of the Atari Operating System ROM programs, 
a sector may not be written directly from a memory area in which the low 
byte of the bottom location is $7F. The system will hang if this is 
attempted. This is not a valFORTH bug, it is Atari's. Please watch out 
for it. 


i 
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valFORTH Memory Map 


STANDARD DISPLAY 
MEMORY AREA 


DP 

LIMIT 

FIRST 

$0700 

$0600 

$05FF 

$057E 


GENERAL BUFFER 



WORD BUFFER 


DICTIONARY 

DISK BUFFERS 

2112 BYTES DECIMAL 
(RELOCATABLE) 


(TASK) 

KERNEL 


BOOT CODE 



ATARI FLOATING POINT 


PAD 

$0080 BYTES 


USE 

PREV 

0 +ORIGIN 


$0480 

$01FF- 

RP- 

$ 0100 - 

$00FF 

$00D4 

Z PAGE 


USER AREA 


RETURN STACK _ 

_ 

_TERMINAL BUFFER 


UP 

RO 

IN 

TIB 


ATARI FLOATING POINT 



SP IS X REGISTER 

RP IS STACK POINTER 
OF CPU 



Atari is a trademark at Atari. Inc., a division of Warner Communications. 
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valFORTH 1.1 SYSTEM EXTENSIONS 


GRAPHICS, COLORS, AND SOUNDS 


Graphics 

The Graphics package follows the Atari BASIC graphics set as closely as 
possible, and is identical in most respects. As in BASIC, the most complex 
parts of Graphics are DRAWTO (abbreviated "DR.") and FIL, and even these are 
not too obscure. Find the Graphics Demo by looking at the directory start¬ 
ing on screen 170, and load it. Try the word FBOX. Now look at the code 
that produced this effect, if you like. The general explanation is as 
fol1ows: 

Display positions are denoted by two coordinates, a horizontal and a vertical. 
The 0,0 point is in the upper left hand corner, and the vertical coordinate 
increases as you go down the display, while the horizontal coordinate increases 
as you go to the right. This is all familiar from BASIC. 

In graphics modes, a single point at position X Y can be plotted by X Y PLOT. 
The color of the point will be that in the color register declared by the 
last COLOR command. A line, again of the color in the register declared by 
the last color command, may then be drawn to point XI Y1 by XI Y1 DR. . The 
word FIL may be used to fill in an area as described in the Atari manual, 
and as illustrated in the FBOX example. The color register for the fill is 
the one whose number is on the stack when FIL is executed. Essentially, to 
set up FIL you draw in boundaries and pick two points you wish to FIL between. 
The first of these points is set up either by a DR. or PLOT command, or by 
valFORTH's POSIT command. POSIT has the advantage of not requiring that you 
put anything into the place where you are positioning yourself. The second 
point for the FIL command is then set up by using POS. . The fill is then 
performed by putting a number on stack (the color register for the fill) and 
then doing FIL. 

If you are in a text mode, a single character, c , can be sent to the display 
by ASCII c CPUT. Text strings can be sent to the display with G" cccc " and 
in addition will have the color in the register specified by the last COLOR 
command before the string is output. This is a significant enhancement to 
BASIC. 
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Graphics and Color Glossary: 


SETCOLOR nl n2 n3 - 

Color register nl (0...3 and 4 for background) is set to hue n2 (0 to 15) 
and luminance n3 (0-14, evens). 

SE. nl n2 n3 — 

Alias for SETCOLOR. 


GR. n — 

Identical to GR. in BASIC. Adding 16 will suppress split display. 
Adding 32 will suppress display preclear. In addition, this GR. will 
not disturb player/missiles. 

POS. x y — 

Same as BASIC POSITION or POS. Positions the invisible cursor if in 
a split display mode, and the text cursor if in 0 GR. . 

POSIT x y — 

Positions and updates the cursor, similar to PLOT, but without changing 
display data. 

PLOT x y — 

Same as BASIC PLOT. PLOTS point of color in register specified by last 
COLOR command, at point x y. 


DRAWTO x y — 

Same as BASIC DRAWTO. Draws line from last PLOT'ted, DRAWTO'ed or 
POSIT'ed point to x y, using color in register specified by last COLOR 
command. 

DR. x y -- 

Alias for DRAWTO. 

FIL b — 

Fills area between last PLOT’ed, DRAWTO'ed or POSIT'ed point to last 
position set by POS., using the color in register b. 

G" — 

Used in the form G" ccccc". Sends text cccc to text area in non-0 
Graphics mode, starting at current cursor position, in color of 
register specified by last COLOR command prior to cccc being output. 

G" may be used within a colon definition, similar to .". 

GTYPE addr count — 

Starting at addr, output count characters to text area in non-0 Graphics 
mode, starting at current cursor position, in color of register speci¬ 
fied by last COLOR command. 

LOC. x y — b 

Positions the cursor at x y and fetches the data from display at that 
position. Like BASIC LOCATE and LOC. . Note that since the word LOCATE 
has a different meaning in valFORTH (it is part of the advanced editor 
in the Utilities/Editor package), the name is not used in this package. 
(Advanced users: We could put Graphics in its own vocabulary, but this 
would add some inconvenience.) 
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( 6 ") 

Run-time code compiled in by G". 

P0S@ -- x y 

Leaves the x and y coordinates of the cursor on the stack. 

CPUT b — 

Outputs the data b to the current cursor position. 

CGET — b 

Fetches the data b from the current cursor position. 

>SCD cl -- c2 

Converts cl from ATASCII to its display screen code, c2. 

Example: ASCII A >SCD 88 @ C! 

will put an "A" into the upper left corner of the display. 

SCD> cl - c2 

Converts cl from display screen code to ATASCII c2. 

See >SCD. 

>BSCD addrl addr2 count — 

Moves count bytes from addrl to addr2, translating from ATASCII 
to display screen code on the way. 

BSCD> addrl addr2 count — 

Moves count bytes from addrl to addr2, translating from display 
screen code to ATASCII on the way. 

COLOR b — 

Saves the value b in the variable COLDAT. 

CLRBYT — addr 

Variable that holds data from last COLOR command. 

GREY — 0 

GOLD — 1 

ORNG — 2 

RDORNG — 3 

PINK — 4 
LVNDR — 5 

BLPRPL - 6 

PRPLBL — 7 

BLUE — 8 
LTBLUE - 9 

TURQ - 10 
GRNBL — 11 
GREEN — 12 
YLWGRN — 13 
ORNGRN — 14 
LTORNG - 15 

B00TC0L0R hue lum — 

Sets up hue for playfield 2 (text background) and lum for playfield 1 
(letter intensity) in 0 Graphics mode. Lum of playfield 2 is set at 4. 
After using B00TC0L0R, doing SAVE will create a system disk with the 
selected color. 
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Sounds 


The actual production of sound by the Atari machines is rather complex and 
the reader is referred to the many recent (first half 1982) articles on this 
subject in various magazines. Here we will restrict conments to the function 
of the Atari audio control register. This is an eight bit register which 
valFORTH shadows by the variable AUDCTL. The bits have the following 
functions: 

bit 7: Change 17 bit polycounter to 9 bit polycounter. 

Affects distortions 0 and 8. 

bit 6: Clock channel 0 with 1.79 Mhz instead of 64 Khz. 

bit 5: Clock channel 2 with 1.79 Mhz instead of 64 Khz. 

bit 4: Clock channel 1 with channel 0 instead of 64 Khz. 

bit 3: Clock channel 3 with channel 2 instead of 64 Khz. 

bit 2: Use channel 2 as crude high-pass on channel 0. 
bit 1: Use channel 3 as crude high-pass on channel 1. 
bit 0: Change normal 64 Khz to 15 Khz. 

The value n may be sent to the audio control register by doing n FILTER!. 

SOUND chan freq dist vol — 

Sets up the sound channel "chan" as indicated. 

Channel: 0-3. 

Frequency: 0-255, 0 is highest pitch. 

Distortion: 0-14, evens only. 

Volume: 0-15. 

Suggested mnemonic: CatFish Don't Vote 

SO. chan freq dist vol -- 

Alias of SOUND. 

FILTER! n — 

Stores n in the audio control register and into the valFORTH shadow 
register, AUDCTL. Use AUDCTL when doing bit manipulation, then do 
FILTER!. (FILTER! does a number of housekeeping chores, so use it 
instead of a direct store into the hardware register.) 

AUDCTL — addr 

A variable containing the last value sent to the audio control register 
by FILTER!. Used for bit manipulation since the audio control register 
is write-only. 

XSND n — 

Silences channel n. 

XSND4 

Silences all channels. 


i 
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TEXT OUTPUT AND DISK PREPARATION GLOSSARY 


S: flag — 

If flag is true, enables handler that sends text to text screen. If 
false, disables the handler. (See PFLAG in main glossary.) ON S: etc. 

P : flag - 

If flag is true, enables handler that sends text to printer. If false, 
disables the handler. (See PFLAG in main glossary.) OFF P: etc. 


BEEP — 

Makes a raucous noise from the keyboard. Is put in this package for 
lack of a better place. 

ASCII c, — n (executing) 
c, — (compiling) 

Converts next character in input stream to ATASCII code. If executing, 
leaves on stack. If compiling, compiles as literal. 


EJECT — 

Causes a form feed on smart printers if the printer handler has been 
enabled by ON P:. May need adjustment for dumb or nonstandard printers. 

LISTS start count -- 

From start, lists count screens. May be aborted by CONSOLE button at 
the end of a screen. 

PLIST scr — 

Lists screen scr to the printer, then restores former printer handler 
status. 

PLISTS start cnt -- 

From start, lists cnt screens to printer three to a page, then restores 
former printer handler status. May be aborted by CONSOLE button at the 
end of a screen. 

FORMAT — 

With prompts, will format a disk in drive of your choice. 

(FMT) nl — n2 

Formats disk in drive nl. Leaves 1 for good format, otherwise error number. 
Note: Because of what appears to be an OS peculiarity, this operation must 
not be the first disk access after a boot. 

DISKC0PY1 — 

With prompts, copies a source to a destination disk on single drive, 
with swapping. Smart routine uses all memory from PAD to bottom of 
Display List, producing minimum number of swaps. 

DISKC0PY2 — 

With prompts, copies disk in drive 1 to disk in drive 2 using memory 
like DISKC0PY1. 
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DEBUGGING UTILITIES 


DECOMP cccc 

Does a decompilation of the word cccc if it can be found in the active 
vocabularies. 

Although DECOMP is very smart, like most FORTH decompilers it will 
become confused by certain constructs, and will begin to print trash, 
with pauses in between while it looks for more trash to print. When 
this happens, simply hold down a CONSOLE button until DECOMP exits. 
This sometimes takes as much as 10 seconds, depending on luck. 


CDUMP addr n — 

A character dump from addr for at least n characters. (Will always 
do a multiple of 16.) 

#DUMP addr n — 

A numerical dump in the current base for at least n characters. 

(Will always do a multiple of 8.) 

(FREE) — n 

Leaves number of bytes between bottom of display list and PAD. This is 
essentially the amount of free dictionary space, if additional memory 
is not being used for player/missiles, extra character sets, and so on. 


FREE — 

Does (FREE) and then prints the stack and "bytes". 

H. n — 

Prints n in HEX, leaves BASE unchanged. 

STACK flag - 

If flag is true, turns on visible stack. If flag is false, turns off 
visible stack. 

• S 

Does a signed, nondestructive stack printout, TOS at right. Also 
sets visible stack to do signed printout. 


U.S ... — ... 

Does unsigned, nondestructive stack printout, TOS at right. Also 
sets visible stack to do unsigned printout. 


B? 

Prints the current base, in decimal. Leaves BASE undisturbed. 

CFALIT cccc, — cfa (executing) 

cccc, — (compiling) 

Gets the cfa (code field address) of cccc. If executing, leaves it on 
the stack; if compiling, compiles it as a literal. Not precisely a 
debugging tool, but finds use in DECOMP. 



FLOATING POINT WORDS 


The floating-point package uses the Atari floating point routines in the 
operating system ROM in the same way that Atari Basic does. The routines 
are rather slow, and there are no trigonometric functions internal to the 
Atari. (SIN, COS, TAN, ATN, and ATN2 have been programmed and are available 
in the Advanced Graphics/Floating Point Package.) LOG and EXP are included in the 
operating system ROM and are supported in the present package, in base 10 
and base e. Note that in the directory on screen 170 it is indicated that 
the ASSEMBLER must be loaded before loading the floating-point package. 

Floating point words have a six byte representation in the Atari OS, and since 
the stack has a 60 byte maximum, a maximum of 10 floating point numbers can be 
on the stack at a time. In practice, this maximum often becomes 9 since some 
fp routines use the stack as a scratch area. 

Operations involving floating-point numbers generally leave floating-point 
results. Exceptions are the words FIX, which takes a positive floating 
pointer number less than 32767.5 and leaves a rounded integer; and the 
floating-point comparison operators, F=, F<, etc., which leave flags. To 
get a floating-point number on the stack, use the word FLOATING or its alias, 

FP, followed by a number in Fortran "E" format. For example. 


FP 

12345 

FP 

12345.6 

FP 

-12345.8 

FP 

+5432E-16 

FP 

-8E18 


will all leave floating-point numbers on the stack. Floating-point variables 
and constants are also supported. 

It has been our experience that mistakes are common when first using this 
package. One must remember to use F* and not *, F+ and not +, and so on, 
when doing fp operations. Remember also that integers and fp numbers can't 
be mixed by operations: Either convert the fp number by FIX, or the integer 
by FLOAT, and then use the appropriate operation. 

Create new words as usual. For instance, to define a floating-point square 
root function, write 

: FSQRT ( fp — fp ) 

LOG FP 2 F/ EXP ; 

Overflow and underflow, and illegal operations such as dividing by 0, taking 
logarithms of negative numbers, or Fixing a negative number cause undefined 
and rather unpredictable results, though they do not harm the system. 
(Additional words in the Utilities/Editor Package cause all but one of these 
operations to give correct or useable results; logarithms of negatives cannot 
be approximated with Real numbers.) 

The maximum and minimum numbers are generous, about 1E97 and IE-97, and it is 
sometimes possible to exceed these limits during computation. Atari's internal 
representation of floating point numbers is awkward. Refer to the Atari OS 
manual, available from Atari, for details if,needed. 



FLOATING-POINT GLOSSARY 


In the following, "fp" is used to indicate a floating-point number (six bytes) 
on the stack. The terms "top-of-stack," "2nd-on-stack" etc., have been used 
with the obvious meanings even though, because fp numbers are six bytes, their 
physical positions on the stack will not match the usual ones. 

FCONSTANT cccc, fp — 

cccc: —fp 

The character string is assigned the constant value fp. When cccc is executed, 
fp will be put on the stack. 

Example: FP 3.1415926 FCONSTANT PI 

FVARIABLE cccc, fp — 

cccc: addr — 

The character string cccc is assigned the initial value fp. When cccc is 
executed, the addr (two bytes) of the value of cccc will be put on the stack 
Example: FP 0 FVARIABLE X 

FP 18.4 X F! 

FDUP fpl — fpl fpl 

Copies the fp number at top-of-stack. 

FDROP fp — 

Discards the fp number at top-of-stack. 

FOVER fp2 fpl — fp2 fpl fp2 

Copies the fp number at 2nd-on-stack to top-of-stack. 

FLOATING cccc. — fp 

Attempts to convert the following string, cccc, to a fp number. Stops on 
reaching first unconvertible character and skips the rest of the string. If 
no characters convertible, leaves unpredictable fp number on stack. 

FP cccc, --fp 

Alias for FLOATING. 

F@ addr — fp 

Fetches the fp number whose address is at top-of-stack. 

FI fp addr — 

Stores fp into addr. Remember that the operation will take six bytes in 
memory. 

F. fp - 

Type out the fp number at top-of-stack. Ignores the current value in BASE 
and uses base 10. 

F? addr — 

Fetches a fp number from addr and types it out. 


i 
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F+ fp2 fpl — fp3 

f Replaces the two top-of-stack fp Items, fp2 and fpl, with their fp sum, fp3. 

F- fp2 fpl - fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their difference, 
fp3=fp2-fpl. 

F* fp2 fpl — fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their product, fp3. 
F/ fp2 fpl - fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their quotient, 
fp3=fp2/fpl. 

FLOAT n - fp 

Replaces number at top-of-stack with its fp equivalent. 

FIX fp (non-neg, less than 32767.5) — n 

Replaces fp number at top-of-stack, constrained as indicated, with its 

integer equivalent. 

LOG fpl — fp2 

Replaces fpl with its base e logarithm, fp2o Not defined for fpl negative. 
L0G10 fpl -- fp2 

Replaces fpl with its base 10 decimal logarithm, fp2. Not defined for fpl 
negative. 

i 

EXP fpl - fp2 

Replaces fpl with fp2, which equals e to the power fpl. 

EXP10 fpl--fp2 

Replaces fpl with fp2, which equals 10 to the power fpl. 

F0= fp -- flag 

If fp is equal to floating-point 0, a true flag is left. Otherwise, a false 
flag is left. 

F= fp2 fpl -- flag 

If fp2 is equal to fpl, a true flag is left. Otherwise, a false flag is left. 
F> fp2 fpl -- flag 

If fp2 is greater than fpl, a true flag is left. Otherwise, a false flag is 
left. 

F< fp2 fpl — flag 

If fp2 is less than fpl, a true flag is left. Otherwise, a false flag is left. 
FLITERAL fp -- 

If compiling, then compile the fp stack value as a fp literal. This definition 
is immediate so that it will execute during a colon definition. The intended 
use is: 

( : xxx [ calculate ] FLITERAL ; 

Compilation is suspended for the compile time calculation of a value. 
Compilation is resumed and FLITERAL compiles the value on stack. 
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FLIT - fp 

Within a colon definition, FLIT is automatically compiled before each fp 
number encountered as input text. Later execution by the system of FLIT as 
it is encountered in the dictionary cause the context of the next 6 dictionary 
addresses to be pushed to the stack as a fp number. FLIT is also compiled 
in explicitly by FLITERAL. 

ASCF addr — fp 

An ASCII-to-floating-point conversion routine. Uses Atari OS routine. The 
routine reads string starting at addr and attempts to create a floating point 
number. If string is not a valid ASCII floating-point representation, leaves 
undefined result on stack. Used by FLOATING. 

FS fp - 

System routine. Sends fp argument on stack to Atari register FRO. Experts 
only. 

>F - fp 

System routine. Fetches fp argument from Atari register FRO. Experts only. 

<F fpl fp2 — 

System routine. Sends fpl and fp2 to Atari registers FR1 and FRO respectively. 
Experts only. 

F.TY 

System routine. Types out last fp number converted by FASC. 

CIX addr -- 

System variable. One byte offset pointer in buffer pointed to by INBUF. 

Experts only. 

INBUF addr — 

System variable. Used by ASCF to know where ASCII string to be converted is 
located. 


FR1 — n 

System constant. Atari 

FRO —n 

System constant. Atari 


internal register address, 
internal register address. 


FPOLY addr count — 

A system routine for advanced users doing polynomial evaluation. 

The polynomial P(Z) = SUM(i=0 to n) (A(i)*Z**i) is computed by the following 
standard method: 

P(Z) = (...(A(n)*Z + A(n-l))*Z + ... + A(1))*Z + A(0) 

The address addr points to the coefficients A(i) stored sequentially in memory, 
with the highest order coefficient first. The count is the number of coeffi¬ 
cients in the list. The independent variable Z, in floating-point, should be 
sent to FRO using FS. FPOLY is then executed. The result put on the stack 
using >F. Note that FPOLY is intended to be used in a Forth word. 

Trigonometric functions and general polynomial expansions, for example, may 
be defined more simply with the help of this routine. 
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FLG10 

System routine used by L0G10. 

FLG 

System routine used by LOG. 

FEX , 

System routine used by EXP. 

FEXIO 

System routine used by EXP10. 

FDIV 

System routine used by F/. 

FMUL 

System routine used by F*. 

FSUB 

System routine used by F-. 

FADD 

System routine used by F+. 

FPI 

System routine used by FIX. 

IFP 

System routine used by FLOAT. 

FASC 

System routine. Does floating-point-to-ASCII conversion 
in FRO and leaves string at address pointed to by INBUF. 
has most significant bit set. Used by F.TY. 

AFP 

System routine used by ASCF. 


on the fp number 
Last byte of string 
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OPERATING SYSTEM 


This package implements the computer’s Operating System I/O routines. The 
850 (RS-232C) driver package may be loaded into the dictionary by using the 
word RS232, which will then support references to devices "Rl" through "R4," 

The code for this section was originally written by Patrick Mullarky, and 
published through the Atari Program Exchange. It is used here by permission 
of the author. 

OS GLOSSARY 

OPEN addr nl n2 n3 -- n4 

This word opens the device whose name is at addr. The device is opened 
on channel n3 with AUX1 and AUX2 as nl and n2 respectively. The device 
status byte is returned as n4. The name of a device may be produced in 
various ways: For a single character name, say "S" for the screen 
handler, 

ASCII S PAD C! 

will leave the ASCII value of S at PAD. Then 

PAD 803 OPEN 

will open the screen handler on channel 3 with AUX1 = 8 (write only) 
and AUX2 = 0. If you have the UTILITIES/EDITOR Package, longer names 
may be set up simply by using the word " . 

CLOSE n -- 

Closes channel n. 

PUT bl n - b2 

Outputs byte bl on channel n, returns status byte b2. 

GET n - bl b2 

Gets byte bl from,channel n, returns status byte b2. 

GETREC addr nl n2 — n3 

Inputs record from channel n2 up to length nl. Returns status byte n3. 
PUTREC addr nl n2 - n3 

Outputs nl characters starting at addr through channel n2. Returns 
status byte n3. 

STATUS n - b 

Returns status byte b from channel n. 

DEVSTAT n - bl b2 b3 

From channel nl gets device status bytes bl and b2, and normal status 
byte b3. 

SPECIAL bl b2 b3 b4 b5 b6 b7 b8 — b9 

Implements the Operating System "Special" command. AUX1 through AUX6 
are bl through b6 respectively, command byte is b7, channel number is 
b8. Returns status byte b9. 


RS232 

Loads the Atari 850 drivers into the dictionary (approx 1.8K) through 
a three-step bootstrap process. Executing this command more than once 
without turning the 850 off and on again will crash the system. 
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valFORTH Video Editor 1.1 


Overview 

This editor is powerful extension to the valFORTH system designed 
specifically for the Atari 400/800 series of microcomputers. The main purpose 
for this editor is to give the FORTH programmer an easy method of text entry to 
screens for subsequent compilation. The editor has four basic modes of opera¬ 
tion: 

1) It allows entering of new text to a FORTH screen as though 
typing on a regular typewriter. 

2) It allows quick, painless modification of any text with a 
powerful set of single stroke editing commands. 

3) It pinpoints exactly where a compilation error has occurred 
and sets up the editor for immediate correction and 
recompilation. 

4) Given the name of a precompiled word, it locates where the 
original text definition of the word is on disk, if the 
"LOCATOR'' option had been selected when the word was compiled. 

The set of single stroke editing commands is a superset of the functions 
found in the MEMO PAD function of the standard Atari operating system. In 
addition to cursor movement, single character insertion/dele'tion, and line 
insertion/deletion, the editor supports a clear-to-end-of-1ine function, a 
split command which separates a single line into two lines, and a useful insert 
submode usually found only in higher quality word processors. 

In addition, there are provisions for scrolling both forwards and backwards 
through screens, and to save or "forget" any changes made. This is useful at 
times when text is mistakenly modified. 

Also provided is a visible edit storage buffer which allows the user to 
move, replace, and insert up to 320 lines of text at a time. This feature alone 
allows the FORTH programmer to easily reorganize source code with the added 
benefit of knowing that re-typing mistakes are avoided. Usage has shown that 
once edit-buffer management is learned, significant typing and programming 
time can be saved. 

For those times when not programming, the editor can double as a simple 
word processor for writing letters and filling other documentation needs. 

The best method for learning how to use this powerful editor is to enter the 
edit mode and try each of the following commands as they are encountered in 
the reading. 

As stated above, there are four ways in which to enter the video editor. 

The following four commands explain each of the possibilities. Note that the 
symbol "<ret>" indicates that the "RETURN" key is to be typed. 
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V view screen ( scr# — 

To edit a screen for the first time, the "View" command is to be 
used. The video display will enter a 32 character wide mode and will 
be broken Into three distinct sections. For example, 

50 V <ret> 

should give something like the display shown in fig. 1. 


Screen #50 U #Bufs: 5 


• ( Example screen ) 

( line 0 ) 

: TEST1 

( line 2 ) 

10 0 


DO 


I CR . 


LOOP ; 


: OCTAL 

( — ) 

8 BASE ! ; 


: +C! 


DUP C@ ROT + 


SWAP C! ; 


(bottom line ) 


Fig. 1 


The top window, composed of a single line, indicates in decimal 
which screen is currently being edited. One should always make a 
practice of checking this screen number to insure that editing will be 
done on the intended screen. Often times, when working with other 
number bases, the wrong screen is called up accidentally and catching 
this mistake early can save time. Also shown is the size of the edit 
buffer (described later). In this example, the buffer is five lines in 
length. This window is known as the heading window. 






valFORTH Video Editor 1.1 


FORTH screens typically are IK (1024 characters) long. Since it is 
impossible to see an entire screen simultaneously, this editor reveals 
only half a screen at a time. There is an "upper" half and a "lower" 
half. In the center of the heading window, either a "U" or an "L" 
is displayed indicating which half of the current screen is being viewed. 
If the valFORTH system is in the half-K screen mode, neither "U" nor "L" 
is displayed since an entire half-K screen can be viewed at one time. 

In figure 1, the upper half of a full-K screen is being viewed. 

The second window (the text window) contains the text found on the 
specified screen. This window is 32 characters wide and 16 lines high. 
The white'cursor (indicated by the symbol "■") will be in the upper- 
lefthand corner of the screen awaiting editing commands. 

The final five-line window found at the bottom of the screen is 
known as the buffer window. This is used for advanced editing and is 
described in greater detail in the section entitled "Buffer Management." 


L re-edit last screen ( --- ) 

This command is used to re-edit the "Last" screen edited. It 
functions identically to the "V" command described above, except no 
screen number is specified. 

Example: L <ret> (re-edit screen 50) 


WHERE find location of error ( — ) 

If, when compiling code, a compilation error occurs, the WHERE 
command will enter the edit mode and position the cursor over the last 
letter of the offending word. The word can then be fixed and the screen 
can be re-compiled. Bear in mind that using the WHERE command prior to 
any occurrence of an error could give strange results. 


LOCATE 


locate definition 


cccc ( — ) 


Once source text has been compiled into the dictionary, it loses 
easy readability to all but experts of the FORTH language. Often_tiir.es, 
though, it is helpful to see what the original source code was. the 
DECOMP command found in the debugger helps tremendously in this regard, 
however, some structures such as IF and DO are still difficult to follow. 
For this reason, the LOCATE command is included with the editor. 


This command accepts a word name, and if at all possible it will 
actually direct the editor to load in the screen where that word was 
defined. This is very helpful at times when one cannot remember where 
the original text was. If the screen shown in figure 1 were loaded and 
the command 

LOCATE +C! <ret> 


were given, the editor would call up screen 50 and position the cursor 
over the word which is the beginning of the definition for "+C! H . 
Typically, the LOCATE command will point to , "COD'." , "CONSTANT" , 
and other defining words. 
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There is a drawback to this feature, however. In order to call up 
any word, the LOCATE conmand must know where the word actually is. 
Normally, when a word is compiled, there Is no way of knowing where it 
was loaded from. Thus for the LOCATE conmand to work, each time a word 
Is entered Into the dictionary, three extra bytes of memory must be used 
to store this lookup information. For an application with many words, 
these extra bytes per word add up quickly, and this is not always 
desirable. For this reason, the LOCATOR command (described below) 
allows the user to enable or disable the storage of this lookup informa¬ 
tion. Only words that were compiled with the LOCATOR option selected 
can be located. If a word cannot be located, the user is warned, or if 
the DEBUGGER is loaded, the word is DECOMPed giving pseudo original code. 


LOCATOR enable/disable location ( ON/OFF — ) 

In order for a word to be locatable using LOCATE, the LOCATOR option 
must have been selected prior to compiling the word. The LOCATOR option 
is selected by executing "ON LOCATOR" and deselected by executing "OFF 
LOCATOR". For example: 

ON LOCATOR 

: PLUS (partial view of a screen) 

: STAR 42 EMIT ; 

OFF LOCATOR 
: NEGATE MINUS ; 

Only the words PLUS and STAR can be located. NEGATE cannot be located 
since the LOCATOR option was disabled. If the DEBUGGER were loaded, 
NEGATE would be decompiled (see the debugger), otherwise, the user would 
be given a warning. The default value for LOCATOR is OFF. 


#BUFS set buffer length ( Clines — ) 

The #BUFS command allows the user to specify the length (in terms of 
number of lines) of the special edit storage buffer. The power of the 
edit buffer lies in the number of lines that can be stored in it. 

Although the default value is five, practice shows that at least 16 
lines should be set aside for this buffer. The maximum number of lines 
allowable is 320which is enough to hold 20 full screens simultaneously. 
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The following sections give a detailed description of all commands which 
the video editor recognizes. A quick reference command list can be found 
following these descriptions. 

Cursor Movement 

• When the edit mode is first entered via the "V" command, a cursor is placed 
in the upper lefthand corner of the screen. 'It should appear as a white block 
and may enclose a black letter. Whenever any key is typed and it is not recog¬ 
nized as an editor command, it is placed in the text window where the cursor 
appears. Likewise, any line functions (such as delete line) work on the line 
where the cursor is found. 


Ctrl a , Ctrl v , Ctrl <, Ctrl > move-cursor commands 

To change the current edit line or character, one of four commands 
may be given. These are known as cursor commands. They are the four 
keys with arrows on them. These keys move the cursor in the direction 
specified by the arrow on the particular key pressed. There are times, 
however, when this is not the case. 

If the current cursor line is the topmost line of the text window, 
and the "cursor-up" command is issued (by simultaneously typing "ctrl" 
and "up-arrow"), the cursor will move to the bottom line of the text 
window. Likewise, a subsequent "cursor-down" command would return the 
cursor to the topmost line of the window. ' Similarly, if the cursor is 
positioned on the leftmost edge and the "cursor-left" comand is given, 
the cursor will "wrap" to the rightmost character ON THE SAME LINE. 

Issuing "cursor-right" will wrap back to the first character on that line. 


RETURN next-line command 

Normally, the RETURN key positions the cursor on the first character 
of the next line. If RETURN is pressed when the cursor is on the lest 
line of the text window (i.e., when the last text line of the screen is 
current), the cursor is positioned in the upper lefthand corner of the 
screen. 


TAB tabulate command 

The TAB key is used to tabulate to the next fixed four column 
tabular stop to the right of the current cursor character. TABbing off 
the end of the current line simply places the cursor at the beginning of 
that same line. 


NOTE: 


Many commands in the editor will "mark" a current FORTH screen as updated 
so that any changes made can be preserved on disk. As simple cursor movement 
does not change the text window in any way, these commands never mar!, the 
current FORTH screen. See the section or, screen management fe>- more informa¬ 
tion. 
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Editing Commands 

Editing commands are those commands which modify the text in some 
predefined manner and mark the current FORTH screen as updated for later 
saving. 


Ctrl INS character insert command 

When the “Insert-character" command Is given, a blank character 
Is Inserted at the current cursor location. The current character and 
all characters to the right are pushed to the right by one character 
position. The last character of the line "falls off" the end and is 
lost. The inserted blank then becomes the current cursor character. 
This is the logical complement to the "delete-character" command 
described below. 


Ctrl DEL delete character command 

When the "delete-character" command is issued, the current cursor 
character is removed, and all characters to the right of the current 
cursor character are moved left one position, thus giving a "squeeze" 
effect. This is normally called "closing" a line. The rightmost 
character on the line (which was vacated) is replaced with a blank. 

This serves as the logical complement to the "insert-command" described 
above. 


shift INS line insert command 

The "line-insert" command inserts a blank line between the current 
cursor line and the line immediately above it. The current line and all 
lines below it are moved down one line to make room for the new line. 

The last line on the screen falls off the bottom and is lost. If this 
command is accidentally typed, the "oops" command (ctrl-0) described 
later can be used to recover from the mistake. Also see the "from buffer" 
command described in the section on buffer management for a similar command. 
This command serves as the logical complement to the "line-delete" command 
described below. 


shift DEL line delete command 

The "line-delete" command deletes the current cursor line. All 
lines below the current line are brought up one line and a blank line 
fills the vacated bottom line of the text window. The deleted line is 
lost. If this command is accidentally issued, recovery can be made by 
issuing the "oops" command (ctrl-0) described later. Also see the 
"to-buffer" command described in the section on buffer management for a 
similar conmand. The "delete-line" command serves as the logical comple 
ment to the "line-insert" conmand. 
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\ 

Ctrl H erase to end of line 

The ’’Hack" command performs a clear-to-end-of-line function. The 
current cursor character and all characters to the right of it on the 
current line are blank filled. All characters blanked are lost. The 
"oops" command described later can be used to recover from an accidentally 
hacked line. 


Ctrl I insert/replace toggle 

In normal operation, any key typed which is not recognized by the 
editor as a control command will replace the current cursor character 
with itself. This is the standard replace mode. Normally, if one 
wanted to insert a character at the current cursor location, the insert 
character command would have to be issued before any text could be 
entered. If inserting many characters, this is cumbersome. 

When active, the insert submode automatically makes room for any 
new characters or words and frees the user from having to worry about 
this. When the editor is called up via the "V" command, the insert mode 
is deactivated. Issuing the insert toggle command will activate it and 
the cursor will blink, indicating that the insert mode is on. Issuing 
the command a second time will deactivate the insert mode and restore 
the editor to the replace mode. Note that while in the insert mode, all 
edit commands (except BACKS, below) function as before. 


BACKS delete previous character 

The BACKS key behaves in two different ways, depending upon whether 
the editor is in the insert mode or in the replace mode. When issued 
while in the replace mode, the cursor is backed up one position and the 
new current character is replaced with a blank. If the cursor is at the 
beginning of the line, the cursor does not move, but the cursor character 
is still replaced with a blank. 

If the editor is in the insert mode, the cursor backs up one 
position, then deletes the new current cursor character and then closes 
the line. If the cursor is at the beginning of the line, the cursor 
remains in the same position, the cursor character is deleted and the 
line closed. 


NOTE: 


As all of the above commands modify the text window in some manner, the 
screen is marked as having been changed. This is to be sure that all changes 
made are eventually saved on disk. The "quit" command described in the section 
on changing screens allows one to unmark a screen so that major mistakes need 
not be saved. 
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Buffer Management 

Much of the utility of the valFORTH editor lies in its ability to tempo¬ 
rarily save text in a visible buffer. To aid the user, it is possible to 
temporarily send text to the buffer and to later retrieve it. This storage 
buffer can hold as many as 3Z0 lines of text simultaneously. This buffer is 
viewed through a 5 line "peephole" visible as the last window on the screen. 
Using this buffer, it is possible to duplicate, move, and easily reorganize 
text, in addition to temporarily saving a line that is about to be edited so 
that the original form can be viewed or restored if necessary. The following 
section will explain exactly how to accomplish each of these actions. 


. Ctrl T to buffer command 

The "to-buffer" command deletes the current cursor line, but 
unlike the "delete-line" command where the line is lost, this conmand 
moves the "peephole" down and copies the line to the bottom line of the 
visible buffer window. This line is the current buffer line. The buffer 
is rolled upon each occurrence of this command so that it may be used 
repeatedly without the loss of stored text. 

For example, if the cursor is positioned on line eight of the display 
shown in figure 1 and the "to-buffer" command is issued twice, the final 
result will be as shown in figure 2. 


Ctrl F from buffer command 

The "from-buffer" command does exactly the opposite of the "to- 
buffer" command described above. It takes the current buffer line and 
inserts it between the current cursor line and the line above it. The 
cursor line and all lines below it are moved down one line with the last 
line of the text window being lost. If the cursor were placed on line 14 
of the above screen display and the "from-buffer" command were issued once, 
the display in figure 3 would result. 
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Screen # 50 U #Bufs: 5 


% 


( Example screen ) 

{ line 0 ) 

1 

V 

• 

: TEST1 

10 0 

DO 

I CR . 

LOOP ; 

( line 2 ) 


Current: 

■ 

: +C! 

DUP C@ ROT + 

SWAP C! ; 




( bottom line ) 


/ 


*L? 


Current: 


: OCTAL ( — ) 

8 BASE ! ; 


fig. 2 


L- 
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Current: 


line was 
rolled to 
the top 

Current: 


Screen # 50 

U #Bufs: 5 


[ Example screen ) { line 0 ) 

: TEST1 
' 10 0 

DO 

I CR . 

LOOP ; 

( line 2 ) 

: +C! 

DUP C@ ROT + 
SWAP C! ; 

■ 8 BASE ! ; 

( bottom line ) 

.. 

8 BASE ! ; 


: OCTAL 

( — ) 




fig. 3 


If the "from-buffer" command is issued again, then lines 13 
through 15 of the text window would look like: 


Current: 


: OCTAL ( — ) 

8 BASE ! ; 

( bottom line ) 


fig. 4 


Note that a block of text has been moved on the screen. Larger 
blocks of text can be moved in the same manner. 


J 
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f Ctrl 

A 

I 

§ 


Ctrl 
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K copy to buffer command 

The "copy-ta-buffer" command takes the current cursor line and 
duplicates it, sending the copy to the buffer. This commands functions 
identically to the "to-buffer" command described above, except that the 
current cursor line is NOT deleted from the text window. 


U copy from buffer 

The “copy-from-buffer" command replaces the current cursor line with 
the current buffer line. This command functions identically to the "from- 
buffer" command described above, except that the buffer line is not inserted 
into the text window, it merely replaces the current cursor line. The 
"oops" command described below can be used to recover from accidental 
usage of this command. 


R roll buffer 

The "roll-buffer" command moves the buffer "peephole" down one line 
and redisplays the visible window. If the buffer were the minimum five 
lines in length, the bottom four lines In the window would move up a line 
and the top line would "wrap" to the bottom and become the current buffer 
line. If there were more than five buffer lines, the bottom four lines 
would move up a line, the topmost line would be pushed up behind the 
peephole, and a new buffer line coming up from below the peephole would 
be displayed and made current. For example, if the buffer were five lines 
long and contained: 


Current: 


( Who? 

) 

( What? 

) 

( When? 

) 

( Where? 

) 

( Why? 

) 


Fig. 5 


the "roll-buffer" command gives: 


Current: 


( What? 

) 

{ When? 

) 

( Where? 

) 

( Why? 

( Who? 

1 


Fig. 6 
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Ctrl B back-rol1-buffer command 

The "back-roll-buffer" does exactly the opposite of the "roll- 
buffer" command described above. For example, if given the buffer in 
figure 6 above, the "back-roll" conmand would give the buffer shown in 
figure 5. 


Ctrl C clear buffer line command 

The 1clear-buffer-line" command clears the current buffer line and 
then "back-rolls" the buffer so that successive clears can be used to 
erase the entire buffer. 


NOTE: 

Any of the above conmands which change the text window will mark the 
current screen as updated. Those conmands which alter only the buffer window 
(such as the "roll" conmand) will not change the status of the current screen. 


J 
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Changing Screens 

There are four ways.in which to leave a FORTH screen. These four methods 
are: moving to a previous screen, moving to a following screen, saving the 
current screen and exiting, or simply aborting the edit session. The four 
commands allowing this'are now described: 


Ctrl P previous screen command 

The "previous-screen" command has two basic functions. If the lower 
part of the current screen is being viewed in the text window, this 
command simply displays the upper portion of the screen. If the upper 
portion is already being viewed, then the "previous-screen" command saves 
any changes made to the current screen and then loads in the screen 
immediately before the current screen. The lower part of the screen 
will then be displayed. If in the half-K screen mode, however, this 
command simply changes screens. 


Ctrl N next screen command 

Like the "previous-screen" command described above, the "next-screen" 
command also has two basic functions. If the upper part of a screen is 
being viewed, this command simply displays the lower portion. If, on the 
other hand, the lower part of the screen is being edited, any changes made 
r to the current screen are saved and the next screen is loaded. 


Ctrl S save command 

The "save" command saves any changes made to the current screen and 
exits the edit mode. The video screen is cleared, and the number of the 
screen just being edited is displayed for reference. Note that it is 
usually a good idea to immediately FLUSH (described in the section on 
screen management below) any unsaved screens. 


Ctrl Q quit command 

The "quit" command aborts the edit session "forgetting" any changes 
made to the text visible in the text window. Changes made on previously 
edited screens will NOT be forgotten. The "quit" command is usually 
used when either the wrong screen has been called up, or if it becomes 
desirable to start over and re-edit the screen again. 
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Special Commands 

There are four special commands in this 'editor which allow greater flexi¬ 
bility in programming on the valFORTH system: 


ESCAPE special key command 

The "special-key" command Instructs the video editor to ignore 
any command function of the key typed next and force a character to the 
screen. Fpr example, normally when "Ctrl >" is typed, the cursor is 
moved right. By typing "ESCAPE Ctrl »" the cursor is not moved — 
rather, the right-arrow is displayed. 


Ctrl A " arrow command 

V vV ^ 


Ctrl J split line comnand ) 


When dealing with FORTH screens, it is often necessary to put the 
FORTH word (pronounced "next screen"), or the ValFORTH word "==>" 

(pronounced "next screen") or the ValFORTH word "==>" (pronounced "next 
half-K screen") at the end of a screen for chaining a long set of words 
together. This command automatically places, or erases, an arrow in the 
lower right hand corner of the text window. If is already there, 

it is replaced with "==>". If "==>" is found, it is erased. (This 
command marks the screen as updated.) 


Often times, for formatting reasons, it is necessary to "split" a 
line into two lines. The split line command takes all characters to the 
left of the cursor and creates the first line, and with the remaining 
characters of the original line, a second line is created. Graphically, 
this looks like: 

before: | The quickabrown fox jumped. | 


after: 1 The quick* I 

j. brown fox jumped. I 

Since a line Is inserted, the bottom line of the text window is lost. 
Using the "oops" command below, however, this can be recovered. 


J 
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s 


L 


Ctrl 0 


oops command 


Occasionally, a line is inserted or deleted accidentally, half a 
line cleared by mistake, or some other major editing blunder is made. 
As the name implies, the "oops" command corrects most of these major 
editing errors. The "oops" command can be used to recover from the 
following commands: 


1) insert line command (shift INS) 

2) delete line comnand (shift DEL) 

3) hack command (ctrl H) 

4) to buffer command (ctrl T) 

5) from buffer command (ctrl F) 

„ 6) copy from buffer command (ctrl U) 

7) split line command (ctrl J) 




U3> The Editor "Splice” Co—nd 


The "splice" command is a new command to the valFORTH 
Video Editor 1.1. It is the complement to the "Split" 
command already available in the editor. Change the two 
screens as shown in the listings and the splice command 
will be installed. Any time ctrl-G is typed, the splice 
command is performed. For example, 

% 

Now is the time 

Ofor all good men 

if ctrl-6 is typed with the setup shown above, a single 
line will result. 


} 

I 


'14' A Quirk in the Editor 

Everv r.ow and then, the video editor will will appear to 
oo on the blink and not accept some ot the legal editing 


control commands. What has happened is that SHIFT-/I\ has 
been typed an<T the editing commands are being 
misinterpreted. Simply type SHIFT-/I\ again. 
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Screen Management 

In addition to the conmands available while in the edit mode, there are 
several other commands Which are for use outside of the edit mode. Typically, 
these commands deal with entire screens at a time. 


FLUSH (_) 

When any changes are made to the current text window, the current 
screen is marked as having been changed. When leaving the edit mode 
using the "save" command, the current screen is sent to a set of internal 
FORTH buffers. These buffers are not written to disk until needed for 
other data. Thus, if no other screen is ever accessed, the buffers will 
never be saved to disk. The FLUSH command forces these buffers to be 
saved if they have been marked as being modified. 

Example: FLUSH <ret> 


EMPTY-BUFFERS ( — ) 

Occasionally, screens are modified temporarily or by accident, and 
get marked as being modified. The EMPTY-BUFFERS command unmarks the 
internal FORTH buffers and fills them with zeroes so that "bad" data are 
not saved to disk. Zero filling the buffers ensures that the next access 
to any of the screens that were in the buffers will load the 
unadulterated copy from disk. The abbreviation MTB is included in the 
valFORTH system to make the use of this command easier. 

Examples: EMPTY-BUFFERS <ret> 

MTB <ret> 


COPY ( from to --- ) 

To duplicate a screen, the COPY command is used. The screen "from" 
is copied to the screen "to" but not flushed. 


Example: 51 60 COPY <ret> 

(Copies screen 51 to screen 60.) 


CLEAR ( scr# — ) 

The CLEAR command fills the specified screen with blanks so that a 
clean edit can be started. The screen is then made current so that the 
L command can be used to enter the edit mode. 

Example: 50 CLEAR <ret> 

(Clears screen 50 and makes it current.) 
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CLEARS ( scr# Iscreens — ) 

The CLEARS command Is used to clear blocks of screens at a time. 
After user verification, it starts with the specified screen and clears 
the specified number of consecutive screens. The first screen cleared 
is made current so that the L command can be used to enter the edit mode. 

Example: 25 3 CLEARS <ret> 

Clear from SCR 25 

to SCR 27 <Y/N> Y 

(Screens 25-27 are cleared. Screen 25 is made current.) 


SMOVE ( from to Iscreens — ) 

The SMOVE command is a multiple screen copy command used for copying 
large numbers of consecutive screens at a time. User verification is 
required by this command to avoid disastrous loss of data. All screens 
to be copied are read into available memory and the user is prompted 
to initiate the copy. This allows the swapping of disks between moves 
to make disk transfers possible. The number of screens the SMOVE command 
can copy at a time is limited only by available memory. 

Example: 50 60 5 SMOVE <ret> 

SMOVE from 50 thru 54 

to 60 thru 64 <Y/N> Y 
Insert source <RETURN> <ret> 

Insert dest. <RETURN> <ret> 

(Transfers the specified screens.) 
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Entering the Edit Mode: 


CeKMiAiJb £oh.H.ARL[ 

> Edit Mode: (executedoutside of the edit mode) 


Enter the edit mode and view the 
specified screen. 


( scr# — ) 


Re-view the current screen. 


( — ) 


WHERE 


Enter the edit mode and position the 
cursor over the word that caused a 
compilation error. 


LOCATE cccc 


LOCATOR 


Enter the edit mode and position the 
cursor over the word defining "cccc". 

( ON/OFF - 

When ON, allows all words compiled until 
the next OFF to be locatable using the 
LOCATE command above. 


#BUFS 


( #lines — 

Sets the length (in lines) of the storage 
buffer. The default is five. 


t I 

A$oueV)s A djiReGsfljMjc.e' usr 

) 

N , 


\/ yb&o 

-rue - wen Kectquvtes. 
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Cursor Movement: 
Ctrl a 

Ctrl v 

Ctrl < 

Ctrl » 

RETURN 

TAB 

Editing Commands: - 
Ctrl INS 

Ctrl DEL 
shift INS 

shift DEL 
Ctrl I 

BACKS 

Ctrl H 


(issued within the edit mode) 

•♦love cursor up one line, wrapping to the bottom 
line if moved off the top. 

Move cursor down one line, wrapping to the top 
line if moved off the bottom. 

Move cursor left one character, wrapping to the 
right edge if moved off the left. 

Move cursor right one character, wrapping to the 
left edge if moved off the right. 

Position the cursor at the beginning of the next 
line. 

Advance to next tabular column. 


(issued within the edit mode) 

Insert one blank at cursor location, losing the 
last character on the line. 

Delete character under cursor, closing the line. 

Insert blank line above current line, losing the 
last line on the screen. 

Delete current cursor line, closing the screen. 

Toggle insert-mode/replace-mode, (see full 
description of Ctrl -I). 

Delete last character typed, if on the same line 
as the cursor. 

Erase to end of line (Hack). 
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Buffer Management: '"* i - (Issued within the edit mode) 

Ctrl T Qelete current cursor line sending it to the 

edit buffer for later use. 

Ctrl F . Take the current buffer line and insert it 
above the current cursor line. 

Ctrl K Copy current cursor line sending it to the 

, edit buffer for later use. 

Ctrl U v- Take the current buffer line and copy it to the 

current cursor line. 

Ctrl R Roll the buffer making the next buffer line 

current. 

Ctrl B Roll the buffer backwards making the previous 

buffer line on the screen current. 

Ctrl C Clear the current buffer line and perform 

a ctrl-B. 

'Note: The current buffer line is last line visible on the video display. 


Changing Screens: 

(issued within the edit mode) 

Ctrl P 

Display the previous screen saving all changes 
made to the current text window. 

Ctrl N 

Display the next screen saving all changes made 
to the current text window. 

Ctrl S 

Save the changes made to the current text window 
and end the edit session. 

Ctrl Q 

Quit the edit session forgetting all changes 
made to current text window. 

Special Keys: 

(issued within the edit mode) 

ESC 

Do not interpret the next key typed as any of 
the commands above. Send it directly to the 
screen instead. 

Ctrl A 

Put >", "*=>", or erase the lower right-hand 

corner of the text window. 

Ctrl J 

Split the current line into two lines at the 
point where the cursor is. 

Ctrl 0 

Corrects any major editing blunders. 


i 
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Screen Management: 
FLUSH 

EMPTY-BUFFERS 


COPY 

CLEAR 


CLEARS 

f 

V 

SMOVE 


(executed outside of the edit mode) 


( — ) 

Save any updated FORTH screens to disk. 


( — ) 

Forget any changes made to any screens not 
yet FLUSHed to disk. Used in "losing" major 
editing mistakes. The abbreviation MTB is 
more commonly used. 


( from to — ) 

Copies screen #from to screen #to. 


( scr# — ) 

Blank fills specified screen. This performs 
the same functions as "WIPE" in Leo Brodie's 
book. 


” { scr# #screens — ) 

Blank fills the specified number of screens 
starting with screen scr#. 


( from to #screens — ) 

Duplicate the specified number of screens 
Starting with screen number "from". Allows 
swapping of disks before saving screens to 
screen number "to". 
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STRING UTILITIES 


The following collection of words describes the string utilities of the 
valFORTH Utilities Package. Strings have been implemented in the FORTH 
language in many different ways. Most implementations set aside space for a 
third stack — a string stack. As strings are entered, they are moved (using 
CMOVE) to this stack. When strings are manipulated on this stack, many long 
memory moves are usually required. This method is typically much slower than 
the method implemented in valFORTH. 

Rather than waste memory space with a third stack, valFORTH uses the 
already existing parameter stack. Unlike the implementation described above, 
valFORTH does not store strings on the stack. Rather, it stores the addresses 
of where the strings can be found.* Using this method, words such as SWAP , 
DUP , PICK , and ROLL can be used to manipulate strings. Routines such as 
string sorts which work on many strings at a time are typically much faster 
since addresses are manipulated rather than long strings. In practice, we 
have found few if any problems using this method of string representation. 


String Glossary 

For the purposes of this section, a string is defined to be a sequence 
of up to 255 characters preceded by a byte indicating its length. The first 
character of the string is referenced as character one. If the length of the 
string is zero, it has no characters and is called the "null" string. In 
stack notation, strings are represented by the symbol $ and the address of the' 
string is stored on the stack rather than the string itself*. 


-TEXT addrl n addr2 — flag 

The word -TEXT compares n characters ataddressl with n characters 
at address2. Returns a false flag if the sequences match, true if they 
don't. Flag is positive if the character sequence at addressl is alpha¬ 
betically greater than the one at address2. Flag is zero if the 
character sequences match, and is negative if the character sequence at 
addressl is alphabetically less than the one at address2. 

-NUMBER addr — d 

-NUMBER functions identically to the standard FORTH word NUMBER 
with the only difference being that -NUMBER does not abort program 
execution upon an illegal conversion. -NUMBER takes the character string 
at addr and attempts to convert it to a double number. On successful 
conversion, the value d is returned with the status variable NFLG set 
to one. On unsuccessful conversion, a double number zero is returned 
with the variable NFLG set to zero. -NUMBER is pronounced "not number". 


♦Representing strings on the stack by their addresses is a very useful concept 
borrowed from MMS Forth (TRS-80), authored by Tom Dowling, and available from 
Miller Microcomputer Services, 617-653-6136. 
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NFLG 
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— addr 

A variable used by -NUMBER that indicates whether the last conversion 
attempted was successful. NFLG is true if the conversion was successful; 
otherwise, it is false. 

UMOVE addrl addr2 n — 

UMOVE is a "universal" memory move. It takes the block of memory 
n bytes long at addrl and copies it to memory location addr2. UMOVE 
correctly uses either CMOVE or <CM0VE so that when a block of memory is 
moved onto part of itself, no data are destroyed. 

" cccc" — (at compile time) 

cccc: -- addr (at run time) . 

If compiling, the sequence cccc (delimited by the trailing ) is 

compiled into the dictionary as a string: 

I Ten I c \ c I c I...I c I . 

All valFORTH strings are represented in this fashion. Since a single 
byte is used to store the length, a maximum string length of 255 is 
allowed. A string with 0 length is called a "null" string. At 
execution time, " puts the address in memory where the string is 
located onto the stack. 

Note that " is IMMEDIATE. When executed outside of a colon 
definition, the string is not compiled into the dictionary, but 
. is stored at PAD instead. 

Example: " This is a string" 

$C0NSTANT cccc $ — (at compile time) 

cccc: -- $ (at execution time) 

Takes the string on top of the stack and compiles it into the 
dictionary with the name cccc. When cccc is later executed, the 
address of the string is pushed onto the stack. 

Example: " Ready? <Y/N> “ $C0NSTANT VERIFY 


$VARIABLE cccc n -- 

cocci •• $ 

Reserves space for a string of length n. When cccc is later 
executed, the address of the string is pushed onto the stack. 

Example: 80 $VARIABLE TEXTLINE 

$. $ — 

Takes the string on top of the stack and sends it to the current 
output device. 

Example: " Hi there" $. <ret> Hi there 

Takes the string at second on stack and stores it at the address 
on top of stack. 

Example: " Store me!" TEXTLINE $! 
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$+ $1 $2 -- $3 

Takes $2 and concatenates it with $1, leaving $3 at PAD. 

Example: , “ Santa " $C0NSTANT 1ST 

M Claus" $CONSTANT LAST 
1ST LAST $+. 

$. <ret> Santa Claus 

LEFTS $1 n — $2 

Returns the leftmost "n" characters of $1 as $2. $2 is stored 
at PAD. 

Example: , " They" 3 LEFTS $. <ret> The 
RIGHTS Si n — $2 

Returns the rightmost "n" characters of $1 as $2. $2 is stored 

at PAD. 

Example: " mother" 5 RIGHTS $• <ret> other 

MID$ $1 n u — $2 

Returns $2 of length u starting with the nth character of $1. 
Recall that the first character of a string is numbered as one. 

Example: " Timeout" 3 2 MID$ $. <ret> me 

LEN S - len 

Returns the length of the specified string. 

ASC $ ~ c 

Returns the ASCII value of the first character of the specified 
string. 

SCOMPARE $1 $2 — flag 

Compares $1 with $2 and returns a status flag. The flag is 

a) positive if $1 is greater than $2 or is equal to $2, but longer, 

b) zero if the strings match and are the same length, and c) negative 
if $1 less than $2 or if they are equal and $1 is shorter than $2. 

$= $1 $2 - flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if the strings match and are equal in length, 
otherwise it is false, 

$< $1 $2 - flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if $1 is less than $2 or if $1 matches $2 but 
is shorter in length, 

$> $1 $2 - flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if $1 is greater than $2 or if $1 matches $2 
but is longer in length. 

SAVES $1 — $2 

As most string operations leave resultant strings at PAD, the word 
SAVES is used to temporarily move strings to PAD+512 so that they can 
be manipulated without being altered in the process. 
f Example: " Wash" SAVES " ington" $+ 
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INSTR 


$1 $2 — n 

Searches $1 for first occurrence of $2. Returns the character 
position in $1 If a match Is found; otherwise, zero is returned. 

Example: * FDCBA" $C0NSTART GRADES 

GRADES " A u INSTR 1- . <ret> 4 

CHR$ . c - $ 

Takes the character "c" and makes it into a string of length one 
and stores It at FAD. 

DVAL $ - d 

Takes numerical string $ and converts it to a double length number. 
The variable NFLG is true if the conversion is successful, otherwise it 
is false. See -NUMBER above. 

Example: " 123" DVAL D. <ret> 123 


VAL $ - n 

Takes the numerical string $ and converts it to a single length 
number. The variable NFLG is true if the conversion is successful, 
otherwise it is false. See -NUMBER above. 

DSTR$ d — $ 

Takes the double number d and converts it to its ASCII representa¬ 
tion as $ at PAD. 

Example: 123 DSTR$ $. <ret> 123 

STR$ n — $ 

Takes the single length number n and converts it to its ASCII 
representation as $ at PAD. 

STRINGS n $1 — $2 

Creates $2 as n copies of the first character of $1. 

#IN$ n — $ 

#IN$ has three similar but different functions. If n is positive, 
it accepts a string of n or fewer characters from the terminal. If n is 
zero, it accepts up to 255 characters from the terminal. If n is nega¬ 
tive, it returns only after accepting -n characters from the terminal. 
The resultant string is stored at PAD. 

IN$ - $ 

Accepts a string of up to 255 characters from the terminal. 

$-TB $1 — $2 

Removes trailing blanks from $1 leaving new $2. 

$1 -- $2 

Exchanges the contents of $1 with $2. 
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ARRAYS and their COUSINS 


/■ 


f 


All of the words described below create structures that are accessed in the 
same way, i.e., by putting the index or indices on the stack and then typing 
the structure's name. The differences are in the ways the structures are 
created. 


The concept of the array should be known from BASIC. While in fig-FORTH 
there is no standard way to implement arrays and similar structures, there 
does exist a general consensus about how this should be done. 

The point on which there is the most divergence of opinion is whether the 
first element in an array should be referred to by the index 0 or 1. We 
select 0 for the first index since this gives much cleaner code and makes 
more sense than 1 after you get used to it. (We've worked with it both ways.) 

ARRAY and CARRAY, and 2ARRAY and 2CARRAY 

The size of an array, specified when it is defined, is the number of elements 
in the array. In other words, an array defined by 


8 ARRAY BINGO 

will have 8 elements numbered 0-7. 
To access an element of an array, do 


n array-name 

to get the address of the nth element on the stack. (You will not be told 
if the number n is not a legitimate index number for the array.) For example, 

5 BINGO 

will leave the address of element number 5 in BINGO on the stack. You can 
store to or fetch from this address as you require. 

The word CARRAY defines a byte or character array. A c-array works the same 
as an array, except that you must use C@ and C! to manipulate single elements, 
rather than @ and !. . • 

The words 2ARRAY ancf2CARRAY each take twcr numbers during definition of a 
2ARRAY or 2CARRAY, and 2ARRAYS and 2CARRAYS take two numbers to access an 
element. Note that when using a 2CARRAY named, say, CHESSBOARD, and a constant 
named ROOK, the two phrases 

ROOK 4 6 CHESSBOARD C! 
and 

ROOK 6 4 CHESSBOARD C! 
don't do the same thing. Also note that the phrase 
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8 8 2CARRAY CHESSBOARD 

defines a 2CARRAY of 8 x 8 » 64 elements, with both indices running from 0 to 
7. • • 

When an ARRAY or a CARRAY is defined, the initial values of the elements 
are undefined. ~ 1 v - - • c - 

TABLE A ND CTABLE _1 . .. . ; 

A cousin of ARRAY Is TABLE. Example: The phrase 

TABLE THISLIST 14 , 18 , -34 , 16 , 

defines a table THISLIST of 4 elements. (The commas above are part of the 
code and must be included.) The number of elements does not have to be 
specified. The elements in THISLIST are accessed using the indices 0-3, 
the same as if it had been defined as an array. The word CTABLE works 
similarly, though using C, instead of , to compile in the numbers. Note that 
negatives won't be compiled in by a C, since in two's complement representation 
negative numbers always occupy the maximum number of bytes. 

VECTOR and CVECTOR 

The last array-type words in this package are CVECTOR and VECTOR. Vector is 
just another name for a list. These words are used when the elements of the 
array you want to create are on the stack, with the last element on top of the 
stack. You just put the number of elements on the stack and the VECTOR or 
CVECTOR, and the name you want to use. Example: 

-3 8 127 899 -43 5 VECTOR POSITIONS 

creates an array named POSITIONS with 5 elements 0-4 with -3 in element 0 
and -43 in element 4. CVECTOR works in a similar way. 




EXAMPLES: 


2 3 BINGO ! 

Stores the value 2 into element 3 of array BINGO. 


2 THISLIST @ 

Will leave the value in element 2 of table THISLIST. 
According to the definition of THISLIST above, this value 
will be -34. 


3 POSITION § . <cr> 899 


i 
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ARRAY WORD GLOSSARY 

ARRAY cccc, n — ** (compiling) 

cccc: *i — addr (executing) 

When compiling, creates an array named cccc with n 16-bit elements numbered 0 
thru n-1. Initial values are undefined. When executing, takes an argument, 
m, off the stack and leaves the address of element m of the array: 

CARRAY cccc, n -- (compiling) 

cccc: m — addr (executing) 

When compiling, creates a c-array named cccc with n 8-bit elements numbered 
0 thru n-1. Initial values are undefined. When executing, takes an argument, 
m, off the stack and leaves the address of element m of the c-array.' 

TABLE cccc, — (compiling) 

cccc: m — addr (executing) 

When compiling, creates a table named cccc but does not allot space. Elements 
are compiled in directly with , (comma). When executing, takes one argument, 
m off the stack and, assuming 16-bit elements, leaves the address of element 
m of the table. 

CTABLE cccc, — (compiling) 

cccc: in — addr (executing) ' j 

When compiling, creates a c-table named cccc but does not allot space. Elements 
are compiled in directly with C, (c-comma). When executing, takes one argument, 
m off the stack and, assuming 8-bit elements, leaves the address of element m 
of the c-table. 

X! nO ... nN count addr — 

Stores count 16-bit words, nO thru nN into memory starting at addr, with nO 
going into addr. Pronounced "extended store." 

XC! bO ... bN count addr — 

Stores count 8-bit words, bO thru bN into memory starting at addr, with bO 
going into addr. Pronounced "extended c-store." 

VECTOR cccc, nO ... nN count — (compiling) 
cccc: m — addr (executing) 

When compiling, creates a vector named cccc with count 16-bit elements 
numbered 0-N. nO is the initial value of element 0, nN is the initial value 

of element N, and so on. When executing, takes one argument, m, off the stack 

and leaves the address of element m on the stack. 

CVECTOR cccc, bO ... bN count — (compiling) 
cccc: m — addr (executing) 

When compiling, creates a c-vector named cccc with count 8-bit elements 
numbered 0-N. bO is the initial value of element 0, bN is the initial value 

of element N, and so on. When executing, takes an argument, m, off the stack 

and leaves the address of element m on the stack. 


L- 
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CASE STRUCTURES 


It often becomes necessary to make many tests upon a single number. 
Typically, this Is accomplished by using a series of nested "DUP test IF" 
statements followed by a series of ENDIFs to terminate the IFs. This is 
arduous and very wasteful of memory, valFORTH contains four very powerful 
Pascal-type CASE statements which ease programming and conserve memory. 


The CASE: structure 
Format; 


CASE: wordname 
wordO 
... wordl 
- • • • 
wordN ; 


The word CASE: creates words that expect a number from 0 to 
N on the stack. If the number is zero, wordO is executed; if the 
number is one, the wordl is executed; and so on. No error checks are 
made to ensure that the case number is a legal value. 

Example: 


: ZERO Zero" ; 

: ONE ." One" ; 

: TWO ." Two" ; 

CASE: NUM 
ZERO 
ONE 
TWO ; 

0 NUM <ret> Zero 

1 NUM <ret> One 

2 NUM <ret> Two 

Note that any other number (e.g. 3 NUM) will crash the system. 






The CASE Structure 


Format: 

: wordname 

‘dk 

wordO 
wordl 
• ♦ • " 

* wordN 

( NOCASE wordnone ) (optional) 

CASEND 


The CASE...CASEND structure is always used within a colon 
definition. Like CASE: above, it requires a number from 
0 and N. However, unlike CASE: above* boundary checks are made 
so that an illegal case will do nothing. If the optional NOCASE 
clause is included then wordnone is executed if an "out of bounds" 
number is used. 

Examples: 

I) 
r 


ZERO Zero" ; 

ONE ." One" ; 

TWO ." Two" ; 


: CHECKNUM ( n — ) 

CASE 
ZERO 
ONE 
TWO 

CASEND ; 


0 CHECKNUM <ret> Zero 

1 CHECKNUM <ret> One 

999 CHECKNUM <ret> (nothing happens) 

2 CHECKNUM <ret> Two 
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II) : GRADEA „ A" ; 

: GRADEB B" ; 

: GRADEC C" ; 

: GRADED D" ; 

: OTHER Failed 1 

DECIMAL 
: GETGRADE 
KEY 65 - 
'CASE 

GRADEA 

GRADEB 

GRADEC 

GRADED 

NOCASE OTHER 
CASEND * ; 


( ~ ) 

(Convert A to 0, B to 1, etc) 


GETGRADE <return and press A> A 
GETGRADE <return and press B> B 
GETGRADE <return and press F> Failed 
GETGRADE <return and press D> D 


The SEL Structure 


Format: 

: wordname 

SEL (Select) 

nl -> wordO 
n2 -> wordl 
0 0 0 

nN > wordN 

( NOSEL wordnone ) (optional) 

SELEND 
« • • « 
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The SEL...SELEND structure Is used when the "selection" numbers 
(nl etc.) are not sequential. This structure is somewhat slower than 
either CASE or CASE: • but is much more general. SEL is typically 
used in operations such as table driver menus where single keystroke 
commands are used. The valFORTH video editor uses the SEL structure 
to implement the many editing keystroke commands. 


Example: 


I) : NICKEL 
: DIME 

: Quarter 

: 4BITS 
: SUSANB 
: BAD$$$ 


nickel." ; 
dime." ; 

." quarter." ; 

." fifty cent piece. 
." dollar" ; 
wooden nickel." 


: MONEY-NAME ( n — ) 

That is called a " 

SEL 

5 -> NICKEL 
*0 -> DIME 
25 -> QUARTER 
50 -> 4BITS 
100 -> SUSANB 

NOSEL BAD$$$ ( this line is optional ) 

SELEND ; 


V 5 MONEY-NAME <ret> That is called a nickel. 

33 MONEY-NAME <ret> That is called a wooden nickel. 
25 MONEY-NAME <ret> That is called a quarter. 


The COND Structure 


Format: 


wordname 




COND 

conditionO 

« 

wordsO 

» 

conditionl 

« 

words1 

» 

• • • 

conditionN 

« 

wordsn 

» 


( NOCOND wordsnone ) (optional) 

CONDEND 
• • • 1 


I 
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Unlike the three previous CASE structures which test for equality, 
the COND structure bases its selection upon any true conditional test 
(e.g. if n > 0 then*..) COND can also be used for range cases. The 
NOCOND clause Is optional and is only executed if no other condition 
passes. Only the code of the first condition that passes will be 
executed. 

Example: 

: EXAM ( score — grade ) 

COND 


90 

>= 

« ." Grade of A" 

4 

» 

80 

>= 

« Grade of B" 

3 

» 

70 

>= 

« ." Grade of C" 

2 

» 

60 

>* 

« ." Grade of D" 

1 

» 


NOCOND ." Not too good" 0 

CONDEND ; - . - 

Note that neither « nor » are needed (nor allowed) around the 
"NOCOND" case. Also note that more than one word can be executed 
between the « and » . 




i 
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DOUBLE NUMBER EXTENSIONS 


The following words extend the set of double number words to be as nearly 
identical as possible to the set in the book Starting FORTH . The exceptions 
are DVARIABLE and DCONSfANT which conform to the FIG standard by expecting 
initial values on the stack. 

All of the single number operations comparable to the double number operations 
below were machine coded; all of the words below (with the exception of DVARIABLE) 
have high-level run time code and so are considerably slower than their single 
number counterparts. 


DOUBLE NUMBER EXTENSION GLOSSARY 

DVARIABLE cccc d— U**. Di 

cccc: — addr 

At compile time, creates a double number variable cccc with the initial value d. 
At run time, cccc leaves the address of its value on the stack. 

DCONSTANT cccc d — 

cccc: ■— d 

At compile time, creates a double number constant cccc with the initial value d. 
At run time, cccc leaves the value d on the stack. 

0 . — 0 . 

A double number constant equal to double number zero. 

1 . -- 1 . 

A double number constant equal to double number one. 

D- dl d2 — d3 

Leaves dl-d2=d3. 

D0= d — flag 

If d is equal to 0. leaves true flag; otherwise, leaves false flag. 

D= dl d2 — flag 

If dl equals d2, leaves true flag; otherwise, leaves false flag. 

D0< d — flag 

If d is negative, leaves true flag; otherwise, leaves false flag. 

D< dl d2 -- flag upiAted 

If dl is less than d2, leaves true flag; otherwise, leaves false flag. 

D> dl d2 — flag 

If dl is greater than d2, leaves true flag; otherwise, leaves false flag. 



DMIN dl d2 — d3 

Leaves the minimum of dl and d2. 

DMAX dl d2 ~ d3 

Leaves the maximum of dl and d2. 

D>R d — 

Sends the double number at top of stack to the return stack. 


Pulls the double number at top of the return stack to the stack. 
D, d -- 

Compiles the double number at top of stack into the dictionary. 


Dlk udl ud2 — flag # _ 

If the unsigned double number udl is less than the unsigned double number ud2, 

leaves a true flag; otherwise, leaves a false flag. 


M+ dl v rr^- d2 ~ - 

Converts n to a double number and then sums with dl. 


<S> A bug in IK 

The word D< ‘fails to work correctly when its two arguments 
•re the negatives of each other (e.g., 20000. and -20000.) 
The following definition (taken from FORTH DIMENSIONS 
Volume IV, Number 1) replaces the one found on screen 121 
of the general utilities package. 


i D< < dl d2 — f > 

ROT 2DUP - 
IF 

<ROT DMINUS D+ 0< 

ELSE 

SWAP < SWAP DROP 
ENDIF 

SWAP DROP | 

Note that there are three additional double length words 
found on screen 120 of the the valGRAPHICS disk. They are 
DU/MOD , D/MOD , and D/ . Here are the definitions for 
two additional words to round out the sett (D* was taken 
from FORTH DIMENSIONS Volume IV, Number 1) 

i DMOD ( dl d2 

D/MOD 2DROP | 

i D* ( dl d2 

OVER 3 PICK U* 

* ROLL 4 ROLL « ♦ 

28MAP • ♦ | 


drem ) 


d3 > 


123 


‘>00— 


ttt 


l 
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MISCELLANEOUS UTILITIES 


This is a grab-bag of useful words. Here they are... 


XR/W #secs addr blk flag — 

"Extended read-write." The same as R/W except that XR/W accepts a sector 
count for multiple sector reads and writes. Starting at address addr and 
block blk, read (flag true) or write (flag false) #secs sectors from or to 
disk. 

SMOVE org des count — 

Move count screens from screen # org to screen # dest. 

The primary disk rearranging word, also used for moving sequences of screens 
between disks. This is a smart routine that uses all memory available below 
the current GR.-generated display list, with prompts for verification and 
disk swap if desired. See valFORTH Editor 1.1 documentation for further detail 

LOADS start count — 

Loads count screens starting from screen # start. This word is used if you 
want to use words that are not chained together by —> 's. It will stop 
loading if a CONSOLE button is held down when the routine finishes loading 
its present screen. 

THRU start finish -- start count 

Converts two range numbers to a start-count format. Example: 

120 130 THRU PLISTS 
will print screens 120 thru 130. 

SEC n — 

Provides an n second delay. Uses a tuned do-loop. 

MSEC n — 

Provides an n millisecond delay, (approx) 

Uses a tuned do-loop. 

H->L n -- b 

Moves the high byte of n to the low byte and zero's the high byte, creating 
b. Machine code. 


L->H nl — n2 

Moves the low byte of nl to the high byte and zero's the low byte, creating 
n2. Machine code. 

H/L nl — nl(hi) nl(lo) 

Split top of stack into two stack items: New top of stack is low byte of old 
top of stack. New second on stack is old top of stack with low byte zeroed. 
Example: HEX 1234 H/L .S <cr> 1200 0034 



BIT b — n 

Creates a number n that has only its bth bit set. The bits are numbered 0-15, 
with zero the least significant. Machine code. 

?BIT nb-f 

Leaves a true flag if the bth bit of n is set. Otherwise leaves a false flag. 
TBIT nl b ~ n2 

Toggles the bth bit of nl, making n2. 

SBIT nl b -- n2 • ^ 

Sets the bth bit of nl, making n2. 

RBIT nl b — n2 

Resets the bth bit of nl, making n2. 

STICK n — horiz vert 

Reads the nth stick (0-3) and resolves the setting into horizontal and 
vertical parts, with values from -1 to +1. -1 -l means up and to the left, 

PADDLE nl — n2 

Reads the nlth paddle (0-7) and returns its value n2. Machine code. 

ATTRACT f — 

If the flag is true, the attract mode is initiated. If the flag is false, 
the attract mode is terminated. 

NXTATR — 

If the system is in the attract mode, this command cycles to the next color 
setup in the attract sequence. Disturbs the timer looked at by 16TIME. 

v 

HLDATR — 

If the system is in attract mode, zero's fast byte of the system timer so 
that attract won't cycle to next color setup for at least four seconds 
or until system timer is changed, say by NXTATR. Disturbs the timer looked 
at by 16TIME. 

16TIME — n 

Returns a 16 bit timer reading from the system clock at locations 19 and 20, 
decimal. This clock is updated 60 times per second, with the fast byte in 
20. Machine code, not fooled by carry. 

8RND — b 

Leaves one random byte from the internal hardware. Machine code. 

16RND — n — 

Leaves one random word from the internal hardware. Machine code with 20 
cycle extra delay for rerandomization. 

' CHOOSE ul — u2 

Randomly choose an unsigned number u2 which is less than ul. 



CSHUFL addr n — 

Randomly rearrange n bytes in memory, starting at address addr. 

Pronounced "c-shuffier" 

SHUFL addr n — 

Randomly rearrange n words in memory, starting at address addr. Pronounced 
"shuffle." SHUFL may also be used to shuffle items directly on the stack by 
doing SP@ n SHUFL. 


n Me 'V 

See DEBUG GTIossary. - v 

A. addr — 

Print the ASCII character at addr, or if not printable, print a period. 

(Used by DUMP). 

DUMP addr n — 

Starting at addr, dump at least n bytes (even multiple of 8) as ASCII and 
hex. May be exited early by pressing a CONSOLE button. 

BLKOP system use only 

BXOR addr count b -- 

Starting at address addr, for count bytes, perform bit-wise exclusive or 
with byte b at each address. Useful for toggling an area of display memory 
to inverse video or a different color, and for other purposes. For instance, 
in 0 GR., do 



DCX 88 0 280 128 BXOR 

Then do Shift-Clear to clear the screen. Pronounced "block ex or." 


BAND addr count b — 

Starting at address addr, for count bytes, perform bit-wise AND with byte b 
at each address. Applications similar to BXOR. 

Pronounced "block and." 

BOR addr count b - 

Starting at address addr, for count bytes, perform bit-wise or with byte b 
at each address. Applications similar to BXOR. 

Pronounced "block or." 

STRIG n - flag 

Reads the button of joystick n (0-3). Leaves a true flag if the button is 
pressed, a false flag if it isn’t. 

PTRIG n — flag 

Reads the button of paddle n (0-7). Leaves a true flag if the button is 
pressed, a false flag if it isn't. 
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